News

Supported by Redmine starting from version 1.1

Manager

All operations on the News resource are provided by its manager. To get access to it you have to call redmine.news where redmine is a configured redmine object. See the Configuration about how to configure redmine object.

Create methods

New in version 2.3.0.

create

redminelib.managers.ResourceManager.create(**fields)

Creates new News resource with given fields and saves it to the Redmine.

Parameters:

  • project_id (int or string) – (required). Id or identifier of News’s project.

  • title (string) – (required). News title.

  • description (string) – (required). News description.

  • summary (string) – (optional). News summary.

  • uploads (list) – (optional). Uploads as [{'': ''}, ...], accepted keys are:

    • path (required). Absolute file path or file-like object that should be uploaded.

    • filename (optional). Name of the file after upload.

    • description (optional). Description of the file.

    • content_type (optional). Content type of the file.

Returns:

Resource object

>>> news = redmine.news.create(title='Foo', description='foobar')
>>> news
<redminelib.resources.News #8 "Foo">

new

redminelib.managers.ResourceManager.new()

Creates new empty News resource but saves it to the Redmine only when save() is called, also calls pre_create() and post_create() methods of the Resource object. Valid attributes are the same as for create() method above.

Returns:

Resource object

>>> news = redmine.news.new()
>>> news.title = 'Foo'
>>> news.description = 'foobar'
>>> news.save()
<redminelib.resources.News #8 "Foo">

Warning

Redmine’s News API doesn’t return a news object after create operation. Due to the fact that it goes against the behaviour of all other API endpoints, Python-Redmine has to do some tricks under the hood to return a resource object which involve an additional API request. If that isn’t desired one should use the following technique:

with redmine.session(return_response=False):
    news = redmine.news.new()
    news.title = 'Foo'
    news.description = 'foobar'
    news.save()

Read methods

get

New in version 2.1.0.

redminelib.managers.ResourceManager.get(resource_id, **params)

Returns single News resource from Redmine by its id.

Parameters:

  • resource_id (int) – (required). News id.

  • include (list) – (optional). Fetches associated data in one call. Accepted values:

    • comments

    • attachments

Returns:

Resource object

>>> news = redmine.news.get(123, include=['comments', 'attachments'])
>>> news
<redminelib.resources.News #123 "Vacation">

Hint

News resource object provides you with on demand includes. On demand includes are the other resource objects wrapped in a ResourceSet which are associated with a News resource object. Keep in mind that on demand includes are retrieved in a separate request, that means that if the speed is important it is recommended to use get() method with include keyword argument. On demand includes provided by the News resource object are the same as in the get() method above:

>>> news = redmine.news.get(123)
>>> news.attachments
<redminelib.resultsets.ResourceSet object with Attachment resources>

all

redminelib.managers.ResourceManager.all(**params)

Returns all News resources from Redmine.

Parameters:

  • limit (int) – (optional). How much resources to return.

  • offset (int) – (optional). Starting from what resource to return the other resources.

Returns:

ResourceSet object

>>> news = redmine.news.all(offset=10, limit=100)
>>> news
<redminelib.resultsets.ResourceSet object with News resources>

filter

redminelib.managers.ResourceManager.filter(**filters)

Returns News resources that match the given lookup parameters.

Parameters:

  • project_id (int or string) – (required). Id or identifier of news project.

  • limit (int) – (optional). How much resources to return.

  • offset (int) – (optional). Starting from what resource to return the other resources.

Returns:

ResourceSet object

>>> news = redmine.news.filter(project_id='vacation')
>>> news
<redminelib.resultsets.ResourceSet object with News resources>

Hint

You can also get news from a Project resource object directly using news relation:

>>> project = redmine.project.get('vacation')
>>> project.news
<redminelib.resultsets.ResourceSet object with News resources>

Update methods

New in version 2.3.0.

update

redminelib.managers.ResourceManager.update(resource_id, **fields)

Updates values of given fields of a News resource and saves them to the Redmine.

Parameters:

  • resource_id (int) – (required). News id.

  • title (string) – (optional). News title.

  • description (string) – (optional). News description.

  • summary (string) – (optional). News summary.

Returns:

True

>>> redmine.news.update(1, title='Bar', description='barfoo', summary='bar')
True

save

redminelib.resources.News.save(**attrs)

Saves current state of a News resource to the Redmine. Attrs that can be changed are the same as for update() method above.

Returns:

Resource object

>>> news = redmine.news.get(1)
>>> news.title = 'Bar'
>>> news.description = 'barfoo'
>>> news.summary = 'bar'
>>> news.save()
<redminelib.resources.News #1 "Bar">

New in version 2.1.0: Alternative syntax was introduced.

>>> news = redmine.news.get(1).save(
...     title='Bar',
...     description='barfoo',
...     summary='bar'
... )
>>> news
<redminelib.resources.News #1 "Bar">

Delete methods

New in version 2.3.0.

delete

redminelib.managers.ResourceManager.delete(resource_id)

Deletes single News resource from Redmine by its id.

Parameters:

resource_id (int) – (required). News id.

Returns:

True

>>> redmine.news.delete(1)
True
redminelib.resources.News.delete()

Deletes current News resource object from Redmine.

Returns:

True

>>> news = redmine.news.get(1)
>>> news.delete()
True

Export

New in version 2.0.0.

redminelib.resultsets.ResourceSet.export(fmt, savepath=None, filename=None)

Exports a resource set of News resources in one of the following formats: atom

Parameters:

  • fmt (string) – (required). Format to use for export.

  • savepath (string) – (optional). Path where to save the file.

  • filename (string) – (optional). Name that will be used for the file.

Returns:

String or Object

>>> news = redmine.news.all()
>>> news.export('atom', savepath='/home/jsmith', filename='news.atom')
'/home/jsmith/news.atom'