core#

class namefile.core.FileInfo(stem: str, suffix: None | str = None, tags: list[str] = <factory>, date: None | datetime.date = None, version: None | Version = None)#

Bases: object

FileInfo ValueObj

we use this class to represent file meta info, such as stem, tags, date, version and suffix, and we can call name() to generate file name by this meta info.

Example

>>> fileinfo = FileInfo('foo', 'txt', ['bar', 'baz'], datetime.date(2020, 1, 1), Version('1.0.0'))
>>> str(fileinfo)
'foo-bar-baz.20200101.1.0.0.txt'
Parameters:

  • stem (str) – Stem of file, in __post_init__(), it will be sanitized by sanitize_stem().

  • suffix (str | None) – Suffix of file.

  • tags (list[str]) – Tags of file, in __post_init__(), tags will be deduplicated and sorted.

  • date (datetime.date | None) – Date of file.

  • version (packaging.version.Version | None) – Version of file.

Warning

  • stem must not be empty.

  • suffix must be a valid suffix, which means it must be a string ends with a letter.

name() → str#

Generate file name by this file info.

generate file name by stem, tags, date, version and suffix. __str__() is an alias of this method.

Note

  • if suffix is None, it will return a directory name, otherwise it will return a file name.

  • if date is not None, it will be formatted as %Y%m%d and add to file name.

  • if version is not None, it will be formatted as str and add to file name.

  • if tags is not empty, it will be joined by - and add to file name.

Note

this method encode all file meta info to a file name, and parse() is the decode method.

FileInfo -(name())-> file name -(parse())-> FileInfo

Example

>>> fileinfo = FileInfo('foo', 'txt', ['bar', 'baz'], datetime.date(2020, 1, 1), Version('1.0.0'))
>>> fileinfo.name()
'foo-bar-baz.20200101.1.0.0.txt'
>>> fileinfo.name() == str(fileinfo)
True
classmethod parse(file_name: str) → FileInfo#

Parse file name to FileInfo.

Example

>>> fileinfo = FileInfo.parse('foo-bar-baz.20200101.1.0.0.txt')
>>> fileinfo.stem
'foo'
>>> fileinfo.tags
['bar', 'baz']
Parameters:

file_name (str) – File name to parse.

Returns:

Parsed file info.

Return type:

FileInfo

namefile.core.namefile(stem: str, suffix: None | str = None, tags: None | str | Iterable[str] = None, date: None | bool | datetime.date | datetime.datetime = False, version: None | str | Version = None) → str#

Helper function to generate file name by FileInfo.

args are same as FileInfo.

Example

>>> fileinfo = namefile('foo', 'txt', ['bar', 'baz'], datetime.date(2020, 1, 1), Version('1.0.0'))
>>> str(fileinfo)
'foo-bar-baz.20200101.1.0.0.txt'
namefile.core.nameparse(file_name: str) → FileInfo#

Helper function to parse file name to FileInfo.

Example

>>> fileinfo = nameparse('foo-bar-baz.20200101.1.0.0.txt')
>>> fileinfo.stem
'foo'
>>> fileinfo.tags
['bar', 'baz']
namefile.core.sanitize_stem(stem: str) → str#

Sanitize stem by replacing invalid characters with underscores.

invalid characters are: . - / and <space>

Parameters:

stem (str) – Stem to sanitize.

Returns:

Sanitized stem.

Return type:

str

Example

>>> sanitize_stem('foo/bar')
'foo_bar'
>>> sanitize_stem('foo-bar')
'foo_bar'