{
"info": {
"author": "Kristof Daja",
"author_email": "kristof@daja.hu",
"bugtrack_url": null,
"classifiers": [
"License :: OSI Approved :: MIT License",
"Operating System :: OS Independent",
"Programming Language :: Python :: 3"
],
"description": "# NextFreeFileName\n\nNextFreeFileName is a micro-package aiming to simplify the process of finding the next available filename\nwhen generating files as part of a large process.\n\n## Overview\nTo understand the purpose of NextFreeFileName, walk thorough an exemplary case.
\nLet's suppose the following scenario:\n * You're generating SVG files using the contents of multiple JSON files
\n * The filename of one of your processed JSON file is: `performance_graph.json`
\n * You need to generate 3 SVG files using information from this JSON
\n * You want all your generated SVGs to share a common name (usually the name of the source file) \n * You want to distinguish the generated SVGs by having a numeric suffix in their file names
\n\nTo find the next free filename, you can execute the following statements:
\n```python\nfrom NextFreeFileName import NextFreeFileName\n\nsrc_json = '/tmp/performance_graph.json'\nsvg_out = NextFreeFileName('/tmp/performance_graph.svg')\n```\nIf `/tmp/performance_graph.svg` already exists, `svg_out` returns the following `NextFreeFileName` object:
\n`PosixPath('/tmp/performance_graph_0.svg')`
\nOtherwise the original path is returned with no numeric suffix: `PosixPath('/tmp/performance_graph.svg')`.\n\nFile names can be dynamically generated using the `NextFreeFileName.next()` method.\n\n## Demo\nTo demonstrate a real-world use case, let's generate 4 empty .txt files:\n```python\nfrom NextFreeFileName import NextFreeFileName\n\nout_txt = NextFreeFileName('/tmp/performance_graph.txt') # Can be str OR class 'pathlib.*'\ni = 0\nwhile i < 4:\n with open(out_txt.next(), 'w') as f:\n f.write('Some text...')\n f.close()\n i += 1\n\n```\nResults:\n```bash\nls\n# performance_graph.txt performance_graph_0.txt performance_graph_1.txt performance_graph_2.txt\n```\n\n# API Description\n```python\nclass NextFreeFileName:\n def __init__(self,\n file_path, glue=\"_\", index=0, ignore_reserved=False, resolve_suffix=True, **kwargs):\n \"\"\"\n Takes a path to a file and if already exists, a number gets appended to its end.\n If file exists, glue + index gets appended to it.\n If file does not exist, the initial value of file_path gets returned as Path.\n :param file_path: (str | Path) Path to existing or desired output\n :param glue: (str) Character gluing together the `original file name` and the `index`. Default=_ (underscore)\n :param index: (int) Number to start counting from\n :param ignore_reserved: Set to True if you don't want to compare glue's value to reserved character's list\n :param resolve_suffix: Sets index based on the file name's current numeric suffix (if exists)\n :keyword reserved_characters: (str[]): List of strings added to Reserved Characters\n \"\"\"\n```\n * To initialize `NextFreeFileName`, a value must be provided for `file_path`.
\n**Accepted types**: str or a pathlib-like objects.
\n * By default, filename and the generated integer are glued together with an underscore(`_`).
\n To override it, set the value of `glue` to any valid unicode character. **Exceptions**: ` * / : < > ? \\ | \"`. \n * By default, the generated integer starts at `0`.
\n To override it, set the value of `index` to any valid integer.\n * By default a few characters (see above) are restricted for `glue`.
\n To disable this restriction, set `ignore_reserved` to `True`. \n\n## Reserved Characters\n > File systems have not always provided the same character set for composing a filename.\nBefore Unicode became a de facto standard, file systems mostly used a locale-dependent character set.\nBy contrast, some new systems permit a filename to be composed of almost any character of the Unicode repertoire, \nand even some non-Unicode byte sequences.\nLimitations may be imposed by the file system, operating system, application, or requirements for interoperability \nwith other systems.
\nMany file system utilities prohibit control characters from appearing in filenames. In Unix-like file systems, \nthe null character and the path separator / are prohibited.
\n > File system utilities and naming conventions on Windows prohibit particular characters from appearing in filenames.\n\n > -- [Filename#Reserved characters and words - Wikipedia][1]\n\nTo achieve high cross-platform compatibility, the following characters are restricted by default:\n```python\n@property\ndef _reserved_characters(self):\n return [\n '*', # asterisk/star\n '/', # slash\n ':', # colon\n '<', # less than\n '>', # greater than\n '?', # question mark\n '\\\\', # backslash\n '|', # vertical bar/pipe\n '\"', # quote\n *self._custom_reserved_characters\n ]\n```\n**Parameters**\n * To extend the list of reserved characters, use the `reserved_characters` kwarg when calling `NextFreeFileName`.
\n `reserved_characters` must be list of strings type kwarg.
\n * To disable the reserved character checking, set `ignore_reserved` to `False` when calling `NextFreeFileName`.\n\n# Installation\nTo install NFFN, execute the following steps:\n1. Get the latest [Release](https://github.com/theriverman/NextFreeFileName/releases) or clone the repository:
\n `git clone git@github.com:theriverman/NextFreeFileName.git`\n2. Install to your virtualenv by executing the following command:
\n `python setup.py install`\n3. Import the main class to your project:
\n `from NFFN import NextFreeFileName`\n\nPyPI package may be added later.\n\n# Contributing/Packaging\nTo contribute, fork the repository, commit your changes and open a pull request.
\nThis package is available at PyPI.\n\nTo release a new package over PyPI, issue the following commands:
\n 1. `python3 setup.py sdist bdist_wheel`\n 2. `python3 -m twine upload dist/*`\n\n# Compatibility\nPython 3.6.0 and above.\n\nThis library takes advantage of f-strings [PEP 498](https://www.python.org/dev/peps/pep-0498/) and \nType Hints [PEP 484](https://www.python.org/dev/peps/pep-0484/).\n\n# Copyright\nMIT License\n\n[1]: https://en.wikipedia.org/wiki/Filename#Reserved_characters_and_words\n\n\n",
"description_content_type": "text/markdown",
"docs_url": null,
"download_url": "",
"downloads": {
"last_day": -1,
"last_month": -1,
"last_week": -1
},
"home_page": "https://github.com/theriverman/NextFreeFileName",
"keywords": "",
"license": "",
"maintainer": "",
"maintainer_email": "",
"name": "NextFreeFileName",
"package_url": "https://pypi.org/project/NextFreeFileName/",
"platform": "",
"project_url": "https://pypi.org/project/NextFreeFileName/",
"project_urls": {
"Homepage": "https://github.com/theriverman/NextFreeFileName"
},
"release_url": "https://pypi.org/project/NextFreeFileName/0.0.2/",
"requires_dist": null,
"requires_python": "",
"summary": "Easily find the next free file name",
"version": "0.0.2"
},
"last_serial": 5168092,
"releases": {
"0.0.1": [
{
"comment_text": "",
"digests": {
"md5": "b4dcde3437a397473b458c589be81e3e",
"sha256": "c0571b60566677cd17ad66536f1a7e0a9ccbeab93614ff492fa8094d80777c55"
},
"downloads": -1,
"filename": "NextFreeFileName-0.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b4dcde3437a397473b458c589be81e3e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 5973,
"upload_time": "2019-04-20T15:28:05",
"url": "https://files.pythonhosted.org/packages/1a/c5/cc187e14b125a14abc97bcd023ebda6f1b338d11c59ca826012423599449/NextFreeFileName-0.0.1-py3-none-any.whl"
},
{
"comment_text": "",
"digests": {
"md5": "272947c26aa6e5496574c366acfffe7b",
"sha256": "0a02ecbc2ca9b6e1ca8ed4b7d35599cbacb411e6beb758e166e2a0f0371578f9"
},
"downloads": -1,
"filename": "NextFreeFileName-0.0.1.tar.gz",
"has_sig": false,
"md5_digest": "272947c26aa6e5496574c366acfffe7b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 4097,
"upload_time": "2019-04-20T15:28:07",
"url": "https://files.pythonhosted.org/packages/cf/c8/ea6e248e86503df957632cafe6827c9de5041883a61f263bf687aec621eb/NextFreeFileName-0.0.1.tar.gz"
}
],
"0.0.2": [
{
"comment_text": "",
"digests": {
"md5": "61acc14c23d20a8b7da14ce10a427592",
"sha256": "f753abe9bbd6b36cc6e2861ad4accd4b876df2dbf2a6d805e18b1e0a3fde4485"
},
"downloads": -1,
"filename": "NextFreeFileName-0.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "61acc14c23d20a8b7da14ce10a427592",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 6829,
"upload_time": "2019-04-20T16:23:41",
"url": "https://files.pythonhosted.org/packages/53/a2/6d612092136625384f4efc4604c0932d043b7bf47d4d7989b3db3da8004d/NextFreeFileName-0.0.2-py3-none-any.whl"
},
{
"comment_text": "",
"digests": {
"md5": "b5958c0ef0556a9b348024feab0ac6e1",
"sha256": "1d32a00e294cd5d25fd755f2125e762ca99fd7f8a7487b62989b62b12583f167"
},
"downloads": -1,
"filename": "NextFreeFileName-0.0.2.tar.gz",
"has_sig": false,
"md5_digest": "b5958c0ef0556a9b348024feab0ac6e1",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 4960,
"upload_time": "2019-04-20T16:23:43",
"url": "https://files.pythonhosted.org/packages/a1/ca/18c10277eaa14e06d84236595f27a9ea5d9f5d4bab1f3800a26788f00c07/NextFreeFileName-0.0.2.tar.gz"
}
]
},
"urls": [
{
"comment_text": "",
"digests": {
"md5": "61acc14c23d20a8b7da14ce10a427592",
"sha256": "f753abe9bbd6b36cc6e2861ad4accd4b876df2dbf2a6d805e18b1e0a3fde4485"
},
"downloads": -1,
"filename": "NextFreeFileName-0.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "61acc14c23d20a8b7da14ce10a427592",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 6829,
"upload_time": "2019-04-20T16:23:41",
"url": "https://files.pythonhosted.org/packages/53/a2/6d612092136625384f4efc4604c0932d043b7bf47d4d7989b3db3da8004d/NextFreeFileName-0.0.2-py3-none-any.whl"
},
{
"comment_text": "",
"digests": {
"md5": "b5958c0ef0556a9b348024feab0ac6e1",
"sha256": "1d32a00e294cd5d25fd755f2125e762ca99fd7f8a7487b62989b62b12583f167"
},
"downloads": -1,
"filename": "NextFreeFileName-0.0.2.tar.gz",
"has_sig": false,
"md5_digest": "b5958c0ef0556a9b348024feab0ac6e1",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 4960,
"upload_time": "2019-04-20T16:23:43",
"url": "https://files.pythonhosted.org/packages/a1/ca/18c10277eaa14e06d84236595f27a9ea5d9f5d4bab1f3800a26788f00c07/NextFreeFileName-0.0.2.tar.gz"
}
]
}