| Name | fictus JSON |
| Version |
0.4.0
JSON |
| download |
| home_page | None |
| Summary | Generate a fake file system to create documentation examples. |
| upload_time | 2024-10-07 14:11:49 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.7 |
| license | None |
| keywords |
documentation
fake
directory
filesystem
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
## Fictus
Use `Fictus` to create and output a fictitious file system for sharing in a text driven format.
```Text
🏡kitchen
└─ 📁drawer
├─ 📁forks
│ ├─ 📁old
│ │ └─ 📄pitchfork.bak
│ ├─ 📄dinner.mp3
│ └─ 📄salad.mov
└─ 📁spoons
└─ 📄ladle.psd
```
Use cases include creating output for a wiki page, communicating a folder structure to a colleague over chat, or
mocking a file/folder structure layout before committing to actual creation on disk. Since Fictus mimics a File System,
calling code can create complex loops to build up as little or as much as required to get an idea across.
If needed the virtual file system can be used to create a physical representation on the physical disk.
<HR>
### FictusFileSystem
A Fictus File System starts with instantiating a FictusFileSystem object and, optionally, providing
a root drive name. If one is not provided, a single slash ('/') will be used.
```Python
from fictus import FictusFileSystem
# Create a FictusFileSystem.
ffs = FictusFileSystem("c")
```
The object can then be built up using creation methods, such as `mdir` and `mkfile` and folder traversal can occur
using `cd`.
```Python
# create some directories
ffs.mkdir("/files/docs")
ffs.mkdir("/files/music/folk")
# Create some files in the current working directory (happens to be root).
ffs.mkfile("README.md", "LICENSE.md", ".ignore")
# Change directory to the `docs` and make more files. Start with `/` to traver from root.
ffs.cd("/files/docs")
ffs.mkfile("resume.txt", "recipe.wrd")
# Change directory to `music/folk`. Note the relative cd from the `docs` folder.
ffs.cd("../music/folk")
ffs.mkfile("bing.mp3", "bang.mp3", "bop.wav")
```
<HR>
### FictusDisplay
A FictusDisplay outputs the FFS.
```Python
from fictus import FictusDisplay
ffs.cd("/") # for this example, ensure the cwd is the root of the file system
# Generate a ffs structure to be printed to stdout as text.
display = FictusDisplay(ffs)
display.pprint()
```
Produces:
```Text
c:\
├─ files\
│ ├─ docs\
│ │ ├─ recipe.wrd
│ │ └─ resume.txt
│ └─ music\
│ └─ folk\
│ ├─ bang.mp3
│ ├─ bing.mp3
│ └─ bop.wav
├─ .ignore
├─ LICENSE.md
└─ README.md
```
The display can also be generated in place:
```Python
FictusDisplay(ffs).pprint()
```
The tree displayed starts at current working directory. The same example
above with the current directory set to `c:/files/music` produces:
```Text
music\
└─ folk\
├─ bang.mp3
├─ bing.mp3
└─ bop.wav
```
The display can also be used to generate a physical representation of the Fictus File System.
```Python
from pathlib import Path
path = Path("c:\\fictus")
FictusDisplay(ffs).reforestation(path)
```
This will create all folders and files represented in the FFS under the `path` provided. File internals will be \
an empty `utf-8` string.
<HR>
### Renderer
A FictusDisplay allows customization of the `DOC`, `ROOT`, `FOLDER`, and `FILE` types.
The Renderer can be permanently reassigned using the `renderer` property. Here is an
example that takes advantage of the built-in `emojiRenderer`.
```Python
from fictus.renderer import emojiRenderer
...
# FictusDisplay the ffs structure after a relative change of directory to files/music
ffs.cd("files/music")
# assign a new Renderer to the display - already instantiated in a previous example.
display.renderer = emojiRenderer
# ouptut with the new Renderer applied
display.pprint()
```
This produces:
```Text
📁music
└─ 📁folk
├─ 📄bang.mp3
├─ 📄bing.mp3
└─ 📄bop.wav
```
Previously, the `renderer` was updated so that each call to `pprint` will use
the `emojiRenderer`. If the main renderer is not required to be updated permanently,
use the `pprint` optional argument - `renderer`.
```Python
from fictus.renderer import defaultRenderer
# current renderer is the emojiRenderer
# uses defaultRenderer just this one time
display.pprint(renderer=defaultRenderer)
# use the emojiRenderer that was setup in the previous example set.
display.pprint()
```
<HR>
### RenderTag Customization
Customization may be useful for creating HTML, Markdown, or other custom tags that are
not already provided. A `Renderer` can register valid `RenderTagEnum` types with
`RenderTag` objects. By default, all `RenderTags` contain empty strings. The user
can choose to override any number of tags as required.
You can create a new `Renderer` from scratch and customize the `RenderTag`s that are
appropriate. For example:
```Python
from fictus.renderer import RenderTagEnum, RenderTag
# A customRenderer is created: adds special characters before a File or Folder.
customRenderer = Renderer()
customRenderer.register(RenderTagEnum.FILE, RenderTag("· ", ""))
customRenderer.register(RenderTagEnum.FOLDER, RenderTag("+ ", "\\"))
# Update display_model to the customRenderer
display.renderer = customRenderer
display.pprint()
```
Produces:
```Text
+ music\
└─ + folk\
├─ · bang.mp3
├─ · bing.mp3
└─ · bop.wav
```
One can also create a new `Renderer` object starting with an already applied object and
updating only the Enum value of interest.
```Python
new_renderer = (
display.renderer
) # from previous examples -- this will return customRenderer
new_renderer.register(RenderTagEnum.FOLDER, RenderTag("✓ ", ""))
display.pprint(renderer=new_renderer)
```
And this will, as expected, generate the following:
```
✓ music
└─ ✓ folk
├─ · bang.mp3
├─ · bing.mp3
└─ · bop.wav
```
<hr>
### Install Using Pip
>pip install fictus
### Building/installing the Wheel locally:
To build the package requires setuptools and build.
>python3 -m build
Once built:
>pip install dist/fictus-*.whl --force-reinstall
Raw data
{
"_id": null,
"home_page": null,
"name": "fictus",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "documentation, fake, directory, filesystem",
"author": null,
"author_email": "Jason Brackman <brackman+fictus@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/0d/07/653cc821d5145c62b7dc69857bfa66d1c947d37c13473054719d77ab09ea/fictus-0.4.0.tar.gz",
"platform": null,
"description": "## Fictus\n\nUse `Fictus` to create and output a fictitious file system for sharing in a text driven format.\n\n```Text\n\ud83c\udfe1kitchen\n\u2514\u2500 \ud83d\udcc1drawer\n \u251c\u2500 \ud83d\udcc1forks\n \u2502 \u251c\u2500 \ud83d\udcc1old\n \u2502 \u2502 \u2514\u2500 \ud83d\udcc4pitchfork.bak\n \u2502 \u251c\u2500 \ud83d\udcc4dinner.mp3\n \u2502 \u2514\u2500 \ud83d\udcc4salad.mov\n \u2514\u2500 \ud83d\udcc1spoons\n \u2514\u2500 \ud83d\udcc4ladle.psd\n```\n\nUse cases include creating output for a wiki page, communicating a folder structure to a colleague over chat, or\nmocking a file/folder structure layout before committing to actual creation on disk. Since Fictus mimics a File System,\ncalling code can create complex loops to build up as little or as much as required to get an idea across.\n\nIf needed the virtual file system can be used to create a physical representation on the physical disk.\n<HR>\n\n### FictusFileSystem\nA Fictus File System starts with instantiating a FictusFileSystem object and, optionally, providing\na root drive name. If one is not provided, a single slash ('/') will be used.\n\n```Python\nfrom fictus import FictusFileSystem\n\n# Create a FictusFileSystem.\nffs = FictusFileSystem(\"c\")\n```\n\nThe object can then be built up using creation methods, such as `mdir` and `mkfile` and folder traversal can occur\nusing `cd`.\n\n\n```Python\n# create some directories\nffs.mkdir(\"/files/docs\")\nffs.mkdir(\"/files/music/folk\")\n\n# Create some files in the current working directory (happens to be root).\nffs.mkfile(\"README.md\", \"LICENSE.md\", \".ignore\")\n\n# Change directory to the `docs` and make more files. Start with `/` to traver from root.\nffs.cd(\"/files/docs\")\nffs.mkfile(\"resume.txt\", \"recipe.wrd\")\n\n# Change directory to `music/folk`. Note the relative cd from the `docs` folder. \nffs.cd(\"../music/folk\")\nffs.mkfile(\"bing.mp3\", \"bang.mp3\", \"bop.wav\")\n```\n\n<HR>\n\n### FictusDisplay\nA FictusDisplay outputs the FFS.\n\n```Python\n\nfrom fictus import FictusDisplay\n\nffs.cd(\"/\") # for this example, ensure the cwd is the root of the file system\n\n# Generate a ffs structure to be printed to stdout as text.\ndisplay = FictusDisplay(ffs)\ndisplay.pprint()\n```\n\nProduces:\n\n```Text\nc:\\\n\u251c\u2500 files\\\n\u2502 \u251c\u2500 docs\\\n\u2502 \u2502 \u251c\u2500 recipe.wrd\n\u2502 \u2502 \u2514\u2500 resume.txt\n\u2502 \u2514\u2500 music\\\n\u2502 \u2514\u2500 folk\\\n\u2502 \u251c\u2500 bang.mp3\n\u2502 \u251c\u2500 bing.mp3\n\u2502 \u2514\u2500 bop.wav\n\u251c\u2500 .ignore\n\u251c\u2500 LICENSE.md\n\u2514\u2500 README.md\n```\n\nThe display can also be generated in place:\n\n```Python\nFictusDisplay(ffs).pprint()\n```\n\nThe tree displayed starts at current working directory. The same example\nabove with the current directory set to `c:/files/music` produces:\n\n```Text\nmusic\\\n\u2514\u2500 folk\\\n \u251c\u2500 bang.mp3\n \u251c\u2500 bing.mp3\n \u2514\u2500 bop.wav\n```\n\nThe display can also be used to generate a physical representation of the Fictus File System. \n\n```Python\nfrom pathlib import Path\npath = Path(\"c:\\\\fictus\")\nFictusDisplay(ffs).reforestation(path)\n```\n\nThis will create all folders and files represented in the FFS under the `path` provided. File internals will be \\\nan empty `utf-8` string.\n<HR>\n\n### Renderer\nA FictusDisplay allows customization of the `DOC`, `ROOT`, `FOLDER`, and `FILE` types.\nThe Renderer can be permanently reassigned using the `renderer` property. Here is an\nexample that takes advantage of the built-in `emojiRenderer`. \n\n```Python\nfrom fictus.renderer import emojiRenderer\n...\n# FictusDisplay the ffs structure after a relative change of directory to files/music\nffs.cd(\"files/music\")\n\n# assign a new Renderer to the display - already instantiated in a previous example.\ndisplay.renderer = emojiRenderer\n\n# ouptut with the new Renderer applied\ndisplay.pprint()\n```\n\nThis produces:\n\n```Text\n\ud83d\udcc1music\n\u2514\u2500 \ud83d\udcc1folk\n \u251c\u2500 \ud83d\udcc4bang.mp3\n \u251c\u2500 \ud83d\udcc4bing.mp3\n \u2514\u2500 \ud83d\udcc4bop.wav\n```\n\nPreviously, the `renderer` was updated so that each call to `pprint` will use\nthe `emojiRenderer`. If the main renderer is not required to be updated permanently, \nuse the `pprint` optional argument - `renderer`.\n\n```Python\nfrom fictus.renderer import defaultRenderer\n# current renderer is the emojiRenderer\n\n# uses defaultRenderer just this one time\ndisplay.pprint(renderer=defaultRenderer) \n\n# use the emojiRenderer that was setup in the previous example set.\ndisplay.pprint() \n```\n\n<HR>\n\n### RenderTag Customization\nCustomization may be useful for creating HTML, Markdown, or other custom tags that are\nnot already provided. A `Renderer` can register valid `RenderTagEnum` types with \n`RenderTag` objects. By default, all `RenderTags` contain empty strings. The user\ncan choose to override any number of tags as required.\n\nYou can create a new `Renderer` from scratch and customize the `RenderTag`s that are \nappropriate. For example:\n\n```Python\nfrom fictus.renderer import RenderTagEnum, RenderTag\n\n# A customRenderer is created: adds special characters before a File or Folder.\ncustomRenderer = Renderer()\ncustomRenderer.register(RenderTagEnum.FILE, RenderTag(\"\u00b7 \", \"\"))\ncustomRenderer.register(RenderTagEnum.FOLDER, RenderTag(\"+ \", \"\\\\\"))\n\n# Update display_model to the customRenderer\ndisplay.renderer = customRenderer\ndisplay.pprint()\n```\n\nProduces:\n\n```Text\n+ music\\\n\u2514\u2500 + folk\\\n \u251c\u2500 \u00b7 bang.mp3\n \u251c\u2500 \u00b7 bing.mp3\n \u2514\u2500 \u00b7 bop.wav\n```\n\nOne can also create a new `Renderer` object starting with an already applied object and \nupdating only the Enum value of interest.\n\n```Python\nnew_renderer = (\n display.renderer\n) # from previous examples -- this will return customRenderer\nnew_renderer.register(RenderTagEnum.FOLDER, RenderTag(\"\u2713 \", \"\"))\ndisplay.pprint(renderer=new_renderer)\n```\n\nAnd this will, as expected, generate the following:\n```\n\u2713 music\n\u2514\u2500 \u2713 folk\n \u251c\u2500 \u00b7 bang.mp3\n \u251c\u2500 \u00b7 bing.mp3\n \u2514\u2500 \u00b7 bop.wav\n```\n\n<hr>\n\n### Install Using Pip\n>pip install fictus\n\n### Building/installing the Wheel locally:\nTo build the package requires setuptools and build.\n>python3 -m build\n\nOnce built:\n>pip install dist/fictus-*.whl --force-reinstall\n",
"bugtrack_url": null,
"license": null,
"summary": "Generate a fake file system to create documentation examples.",
"version": "0.4.0",
"project_urls": {
"Homepage": "https://github.com/jasonbrackman/arborator",
"Source": "https://github.com/jasonbrackman/arborator"
},
"split_keywords": [
"documentation",
" fake",
" directory",
" filesystem"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "0e18e30cfa73560ce11f413b19e70dec28f3b9375c9ffe20b8c963721dd78cd5",
"md5": "2823401e7a6d5ee0dd9e88e295b0be6b",
"sha256": "5f45c89c317f63ac145882927bd7b70d0182098016542adbd103335aaae292e9"
},
"downloads": -1,
"filename": "fictus-0.4.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2823401e7a6d5ee0dd9e88e295b0be6b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 9578,
"upload_time": "2024-10-07T14:11:48",
"upload_time_iso_8601": "2024-10-07T14:11:48.305903Z",
"url": "https://files.pythonhosted.org/packages/0e/18/e30cfa73560ce11f413b19e70dec28f3b9375c9ffe20b8c963721dd78cd5/fictus-0.4.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "0d07653cc821d5145c62b7dc69857bfa66d1c947d37c13473054719d77ab09ea",
"md5": "1f8e4226fddd1ea5b37c41be3ce3ef28",
"sha256": "2deb00cc90d50fd446ae893a307c94921f716c2b53383cc06a41537a4c713751"
},
"downloads": -1,
"filename": "fictus-0.4.0.tar.gz",
"has_sig": false,
"md5_digest": "1f8e4226fddd1ea5b37c41be3ce3ef28",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 11535,
"upload_time": "2024-10-07T14:11:49",
"upload_time_iso_8601": "2024-10-07T14:11:49.253688Z",
"url": "https://files.pythonhosted.org/packages/0d/07/653cc821d5145c62b7dc69857bfa66d1c947d37c13473054719d77ab09ea/fictus-0.4.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-07 14:11:49",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "jasonbrackman",
"github_project": "arborator",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "fictus"
}
