File

Supported by Redmine starting from version 3.4

Manager

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

Create methods

create

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

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

Parameters:

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

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

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

  • description (string) – (optional). Description of the file.

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

  • version_id (int) – (optional). File’s version id.

Returns:

Resource object

>>> f = redmine.file.create(
...     project_id='vacation',
...     path='/absolute/path/to/file',
...     filename='foo.txt',
...     description='foobar',
...     content_type='text/plain',
...     version_id=1
... )
>>> f
<redminelib.resources.File #1 "foo.txt">

new

redminelib.managers.FileManager.new()

Creates new empty File 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

>>> f = redmine.file.new()
>>> f.project_id = 'vacation'
>>> f.path = '/absolute/path/to/file'
>>> f.filename = 'foo.txt'
>>> f.description = 'foobar'
>>> f.content_type = 'text/plain'
>>> f.version_id = 1
>>> f.save()
<redminelib.resources.File #1 "foo.txt">

Warning

Redmine’s File API doesn’t return a file 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 with at least an id attribute. That doesn’t involve any additional API requests. In most cases that should be enough, but if it’s not and a complete resource object is needed, one has to use a refresh() method to make an additional query to the Redmine to retrieve a complete resource:

>>> f = redmine.file.new()
>>> f.project_id = 'vacation'
>>> f.path = '/absolute/path/to/file'
>>> f.filename = 'foo.txt'
>>> f.description = 'foobar'
>>> f.content_type = 'text/plain'
>>> f.version_id = 1
>>> f.save()
<redminelib.resources.File #1>
>>> f.refresh()
>>> f
<redminelib.resources.File #1 "foo.txt">

Read methods

get

redminelib.managers.FileManager.get(resource_id)

Returns single File resource from Redmine by its id.

Parameters:

resource_id (int) – (required). Id of the file.

Returns:

Resource object

>>> f = redmine.file.get(12345)
>>> f
<redminelib.resources.File #12345 "foo.txt">

Hint

Files can be easily downloaded via the provided download() method which is a proxy to the redmine.download() method which provides several options to control the saving process (see docs for details):

>>> f = redmine.file.get(12345)
>>> filepath = f.download(savepath='/usr/local/', filename='image.jpg')
>>> filepath
'/usr/local/image.jpg'

all

Not supported by Redmine

filter

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

Returns File resources that match the given lookup parameters.

Parameters:

project_id (int or string) – (optional). Get files from the project with given id.

Returns:

ResourceSet object

>>> files = redmine.file.filter(project_id='vacation')
>>> files
<redminelib.resultsets.ResourceSet object with File resources>

Hint

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

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

Update methods

update

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

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

Parameters:

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

  • filename (string) – (optional). File name.

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

  • content_type (string) – (optional). File content-type.

Returns:

True

>>> redmine.file.update(
...     1,
...     filename='foo.txt',
...     description='foobar',
...     content_type='text/plain'
... )
True

save

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

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

Returns:

Resource object

>>> f = redmine.file.get(1)
>>> f.filename = 'foo.txt'
>>> f.description = 'foobar'
>>> f.content_type = 'text/plain'
>>> f.save()
<redminelib.resources.File #1 "foo.txt">

Added in version 2.1.0: Alternative syntax was introduced.

>>> f = redmine.file.get(1).save(
...     filename='foo.txt',
...     description='foobar',
...     content_type='text/plain'
... )
>>> f
<redminelib.resources.File #1 "foo.txt">

Delete methods

delete

redminelib.managers.FileManager.delete(resource_id)

Deletes single File resource from Redmine by its id.

Parameters:

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

Returns:

True

>>> redmine.file.delete(12345)
True
redminelib.resources.File.delete()

Deletes current File resource object from Redmine.

Returns:

True

>>> f = redmine.file.get(12345)
>>> f.delete()
True

Export

Export functionality doesn’t make sense for files as they can be downloaded