File Module

For more advanced use-cases dealing with the filesystem, the browsepy’s own classes (Node, File and Directory) can be instantiated and inherited.

Node class is meant for implementing your own special filesystem nodes, via inheritance (it’s abstract so shouldn’t be instantiated directly). Just remember to overload its Node.generic attribute value to False.

Both File and Directory classes can be instantiated or extended, via inheritance, with logic like different default widgets, virtual data (see player plugin code).

Node

class browsepy.file.Node(path=None, app=None, **defaults)[source]

Abstract filesystem node class.

This represents an unspecified entity with a filesystem’s path suitable for being inherited by plugins.

When inheriting, the following attributes should be overwritten in order to specify from_urlpath() classmethod behavior:

  • generic, if true, an instance of directory_class or file_class will be created instead of an instance of this class tself.
  • directory_class, class will be used for directory nodes,
  • file_class, class will be used for file nodes.
ancestors[source]

Get list of ancestors until app config’s directory_base is reached.

Returns:list of ancestors starting from nearest.
Return type:list of Node objects
can_download = False
can_remove[source]

Get if current node can be removed based on app config’s directory_remove.

Returns:True if current node can be removed, False otherwise.
Return type:bool
category

Get mimetype category (first portion of mimetype before the slash).

Returns:mimetype category
Return type:str

As of 2016-11-03’s revision of RFC2046 it could be one of the following:

  • application
  • audio
  • example
  • image
  • message
  • model
  • multipart
  • text
  • video
directory_class

alias of Directory

file_class

alias of File

classmethod from_urlpath(path, app=None)[source]

Alternative constructor which accepts a path as taken from URL and uses the given app or the current app config to get the real path.

If class has attribute generic set to True, directory_class or file_class will be used as type.

Parameters:
  • path – relative path as from URL
  • app – optional, flask application
Returns:

file object pointing to path
Return type:

File
generic = True
is_excluded[source]

Get if current node shouldn’t be shown, using :attt:`app` config’s exclude_fnc.

Returns:True if excluded, False otherwise
is_root = False

Get last widget with place “entry-link”.

Returns:widget on entry-link (ideally a link one)
Return type:namedtuple instance
modified

Get human-readable last modification date-time.

Returns:iso9008-like date-time string (without timezone)
Return type:str
name

Get the basename portion of node’s path.

Returns:filename
Return type:str
parent[source]

Get parent node if available based on app config’s directory_base.

Returns:parent object if available
Return type:Node instance or None
pathconf[source]

Get filesystem config for current path. See compat.pathconf().

Returns:fs config
Return type:dict
plugin_manager[source]

Get current app’s plugin manager.

Returns:plugin manager instance
re_charset = re.compile('; charset=(?P<charset>[^;]+)')
classmethod register_directory_class(kls)[source]

Convenience method for setting current class directory_class property.

Parameters:kls (type) – class to set
Returns:given class (enabling using this as decorator)
Return type:type
classmethod register_file_class(kls)[source]

Convenience method for setting current class file_class property.

Parameters:kls (type) – class to set
Returns:given class (enabling using this as decorator)
Return type:type
remove()[source]

Does nothing except raising if can_remove property returns False.

Raises:OutsideRemovableBase if :property:`can_remove` returns false
stats[source]

Get current stats object as returned by os.stat function.

Returns:stats object
Return type:posix.stat_result or nt.stat_result
type

Get the mime portion of node’s mimetype (without the encoding part).

Returns:mimetype
Return type:str
urlpath

Get the url substring corresponding to this node for those endpoints accepting a ‘path’ parameter, suitable for from_urlpath().

Returns:relative-url-like for node’s path
Return type:str
widgets[source]

List widgets with filter return True for this node (or without filter).

Remove button is prepended if :property:can_remove returns true.

Returns:list of widgets
Return type:list of namedtuple instances

Directory

class browsepy.file.Directory(path=None, app=None, **defaults)[source]

Bases: browsepy.file.Node

Filesystem directory class.

Some notes:

  • mimetype is fixed to ‘inode/directory’, so mimetype detection functions won’t be called in this case.
  • is_file is fixed to False, so no further checks are needed.
  • size is fixed to 0 (zero), so stats are not required for this.
  • encoding is fixed to ‘default’.
  • generic is set to False, so static method from_urlpath() will always return instances of this class.
ancestors

Get list of ancestors until app config’s directory_base is reached.

Returns:list of ancestors starting from nearest.
Return type:list of Node objects
can_download[source]

Get if path is downloadable (if app’s directory_downloadable config property is True).

Returns:True if downloadable, False otherwise
Return type:bool
can_remove[source]

Get if current node can be removed based on app config’s directory_remove.

Returns:True if current node can be removed, False otherwise.
Return type:bool
can_upload[source]

Get if a file can be uploaded to path (if directory path is under app’s directory_upload config property).

Returns:True if a file can be upload to directory, False otherwise
Return type:bool
category

Get mimetype category (first portion of mimetype before the slash).

Returns:mimetype category
Return type:str

As of 2016-11-03’s revision of RFC2046 it could be one of the following:

  • application
  • audio
  • example
  • image
  • message
  • model
  • multipart
  • text
  • video
choose_filename(filename, attempts=999)[source]

Get a new filename which does not colide with any entry on directory, based on given filename.

Parameters:
  • filename (str) – base filename
  • attempts (int) – number of attempts, defaults to 999
Returns:

filename
Return type:

str
Raises:
  • FilenameTooLong – when filesystem filename size limit is reached
  • PathTooLong – when OS or filesystem path size limit is reached
contains(filename)[source]

Check if directory contains an entry with given filename.

Parameters:filename (str) – filename will be check
Returns:True if exists, False otherwise.
Return type:bool
directory_class

alias of Directory

download()[source]

Get a Flask Response object streaming a tarball of this directory.

Returns:Response object
Return type:flask.Response
encoding = 'default'
file_class

alias of File

from_urlpath(path, app=None)

Alternative constructor which accepts a path as taken from URL and uses the given app or the current app config to get the real path.

If class has attribute generic set to True, directory_class or file_class will be used as type.

Parameters:
  • path – relative path as from URL
  • app – optional, flask application
Returns:

file object pointing to path
Return type:

File
generic = False
is_directory[source]

Get if path points to a real directory.

Returns:True if real directory, False otherwise
Return type:bool
is_empty[source]

Get if directory is empty (based on _listdir()).

Returns:True if this directory has no entries, False otherwise.
Return type:bool
is_excluded

Get if current node shouldn’t be shown, using :attt:`app` config’s exclude_fnc.

Returns:True if excluded, False otherwise
is_file = False
is_root[source]

Get if directory is filesystem’s root

Returns:True if FS root, False otherwise
Return type:bool

Get last widget with place “entry-link”.

Returns:widget on entry-link (ideally a link one)
Return type:namedtuple instance
listdir(sortkey=None, reverse=False)[source]

Get sorted list (by given sortkey and reverse params) of File objects.

Returns:sorted list of File instances
Return type:list of File instances
mimetype = 'inode/directory'
modified

Get human-readable last modification date-time.

Returns:iso9008-like date-time string (without timezone)
Return type:str
name

Get the basename portion of directory’s path.

Returns:filename
Return type:str
parent

Get parent node if available based on app config’s directory_base.

Returns:parent object if available
Return type:Node instance or None
pathconf

Get filesystem config for current path. See compat.pathconf().

Returns:fs config
Return type:dict
plugin_manager

Get current app’s plugin manager.

Returns:plugin manager instance
re_charset = re.compile('; charset=(?P<charset>[^;]+)')
register_directory_class(kls)

Convenience method for setting current class directory_class property.

Parameters:kls (type) – class to set
Returns:given class (enabling using this as decorator)
Return type:type
register_file_class(kls)

Convenience method for setting current class file_class property.

Parameters:kls (type) – class to set
Returns:given class (enabling using this as decorator)
Return type:type
remove()[source]

Remove directory tree.

Raises:OutsideRemovableBase – when not under removable base directory
size = None
stats

Get current stats object as returned by os.stat function.

Returns:stats object
Return type:posix.stat_result or nt.stat_result
type

Get the mime portion of node’s mimetype (without the encoding part).

Returns:mimetype
Return type:str
urlpath

Get the url substring corresponding to this node for those endpoints accepting a ‘path’ parameter, suitable for from_urlpath().

Returns:relative-url-like for node’s path
Return type:str
widgets[source]

List widgets with filter return True for this dir (or without filter).

Entry link is prepended. Upload scripts and widget are added if :property:can_upload is true. Download button is prepended if :property:can_download returns true. Remove button is prepended if :property:can_remove returns true.

Returns:list of widgets
Return type:list of namedtuple instances

File

class browsepy.file.File(path=None, app=None, **defaults)[source]

Bases: browsepy.file.Node

Filesystem file class.

Some notes:

  • can_download is fixed to True, so Files can be downloaded inconditionaly.
  • can_upload is fixed to False, so nothing can be uploaded to file path.
  • is_directory is fixed to False, so no further checks are performed.
  • generic is set to False, so static method from_urlpath() will always return instances of this class.
ancestors

Get list of ancestors until app config’s directory_base is reached.

Returns:list of ancestors starting from nearest.
Return type:list of Node objects
can_download = True
can_remove

Get if current node can be removed based on app config’s directory_remove.

Returns:True if current node can be removed, False otherwise.
Return type:bool
can_upload = False
category

Get mimetype category (first portion of mimetype before the slash).

Returns:mimetype category
Return type:str

As of 2016-11-03’s revision of RFC2046 it could be one of the following:

  • application
  • audio
  • example
  • image
  • message
  • model
  • multipart
  • text
  • video
directory_class

alias of Directory

download()[source]

Get a Flask’s send_file Response object pointing to this file.

Returns:Response object as returned by flask’s send_file
Return type:flask.Response
encoding

Get encoding part of mimetype, or “default” if not available.

Returns:file conding as returned by mimetype function or “default”
Return type:str
file_class

alias of File

from_urlpath(path, app=None)

Alternative constructor which accepts a path as taken from URL and uses the given app or the current app config to get the real path.

If class has attribute generic set to True, directory_class or file_class will be used as type.

Parameters:
  • path – relative path as from URL
  • app – optional, flask application
Returns:

file object pointing to path
Return type:

File
generic = False
is_directory = False
is_excluded

Get if current node shouldn’t be shown, using :attt:`app` config’s exclude_fnc.

Returns:True if excluded, False otherwise
is_file[source]

Get if node is file.

Returns:True if file, False otherwise
Return type:bool
is_root = False

Get last widget with place “entry-link”.

Returns:widget on entry-link (ideally a link one)
Return type:namedtuple instance
mimetype[source]

Get full mimetype, with encoding if available.

Returns:mimetype
Return type:str
modified

Get human-readable last modification date-time.

Returns:iso9008-like date-time string (without timezone)
Return type:str
name

Get the basename portion of node’s path.

Returns:filename
Return type:str
parent

Get parent node if available based on app config’s directory_base.

Returns:parent object if available
Return type:Node instance or None
pathconf

Get filesystem config for current path. See compat.pathconf().

Returns:fs config
Return type:dict
plugin_manager

Get current app’s plugin manager.

Returns:plugin manager instance
re_charset = re.compile('; charset=(?P<charset>[^;]+)')
register_directory_class(kls)

Convenience method for setting current class directory_class property.

Parameters:kls (type) – class to set
Returns:given class (enabling using this as decorator)
Return type:type
register_file_class(kls)

Convenience method for setting current class file_class property.

Parameters:kls (type) – class to set
Returns:given class (enabling using this as decorator)
Return type:type
remove()[source]

Remove file. :raises OutsideRemovableBase: when not under removable base directory

size

Get human-readable node size in bytes. If directory, this will corresponds with own inode size.

Returns:fuzzy size with unit
Return type:str
stats

Get current stats object as returned by os.stat function.

Returns:stats object
Return type:posix.stat_result or nt.stat_result
type

Get the mime portion of node’s mimetype (without the encoding part).

Returns:mimetype
Return type:str
urlpath

Get the url substring corresponding to this node for those endpoints accepting a ‘path’ parameter, suitable for from_urlpath().

Returns:relative-url-like for node’s path
Return type:str
widgets[source]

List widgets with filter return True for this file (or without filter).

Entry link is prepended. Download button is prepended if :property:can_download returns true. Remove button is prepended if :property:can_remove returns true.

Returns:list of widgets
Return type:list of namedtuple instances

Utility functions

browsepy.file.fmt_size(size, binary=True)[source]

Get size and unit.

Parameters:
  • size (int) – size in bytes
  • binary (bool) – whether use binary or standard units, defaults to True
Returns:

size and unit
Return type:

tuple of int and unit as str
browsepy.file.abspath_to_urlpath(path, base, os_sep='/')[source]

Make filesystem absolute path uri relative using given absolute base path.

Parameters:
  • path – absolute path
  • base – absolute base path
  • os_sep – path component separator, defaults to current OS separator
Returns:

relative uri
Return type:

str or unicode
Raises:

OutsideDirectoryBase – if resulting path is not below base
browsepy.file.urlpath_to_abspath(path, base, os_sep='/')[source]

Make uri relative path fs absolute using a given absolute base path.

Parameters:
  • path – relative path
  • base – absolute base path
  • os_sep – path component separator, defaults to current OS separator
Returns:

absolute path
Return type:

str or unicode
Raises:

OutsideDirectoryBase – if resulting path is not below base
browsepy.file.check_under_base(path, base, os_sep='/')[source]

Check if given absolute path is under given base.

Parameters:
  • path (str) – absolute path
  • base (str) – absolute base path
  • os_sep – path separator, defaults to os.sep
Returns:

wether file is under given base or not
Return type:

bool
browsepy.file.check_base(path, base, os_sep='/')[source]

Check if given absolute path is under or given base.

Parameters:
  • path (str) – absolute path
  • base (str) – absolute base path
  • os_sep – path separator, defaults to os.sep
Returns:

wether path is under given base or not
Return type:

bool
browsepy.file.check_path(path, base, os_sep='/')[source]

Check if both given paths are equal.

Parameters:
  • path (str) – absolute path
  • base (str) – absolute base path
  • os_sep – path separator, defaults to os.sep
Returns:

wether two path are equal or not
Return type:

bool
browsepy.file.secure_filename(path, destiny_os='posix', fs_encoding='utf-8')[source]

Get rid of parent path components and special filenames.

If path is invalid or protected, return empty string.

Parameters:
  • path – unsafe path, only basename will be used
  • destiny_os (str) – destination operative system (defaults to os.name)
  • fs_encoding (str) – fs path encoding (defaults to detected)
Type:

str
Returns:

filename or empty string
Return type:

str
browsepy.file.alternative_filename(filename, attempt=None)[source]

Generates an alternative version of given filename.

If an number attempt parameter is given, will be used on the alternative name, a random value will be used otherwise.

Parameters:
  • filename – original filename
  • attempt – optional attempt number, defaults to null
Returns:

new filename
Return type:

str or unicode
browsepy.file.scandir(path, app=None)[source]

Config-aware scandir. Currently, only aware of exclude_fnc.

Parameters:
Returns:

filtered scandir entries
Return type:

iterator