# mutapath
[](https://github.com/matfax/mutapath/actions)
[](https://codecov.io/gh/matfax/mutapath)
[](https://mutapath.readthedocs.io/en/latest/?badge=latest)
[](https://github.com/matfax/mutapath/issues/270)
[](https://libraries.io/pypi/mutapath)
[](https://www.codefactor.io/repository/github/matfax/mutapath)
[](https://github.com/PyCQA/bandit)
[](https://github.com/psf/black)
[](https://pypi.org/project/mutapath/)
[](https://pypi.org/project/mutapath/)
[](https://pypistats.org/packages/mutapath)
[](https://github.com/matfax/mutapath/releases)
[](https://github.com/matfax/mutapath/commits/main)
[](https://github.com/matfax/mutapath/blob/main/LICENSE)
This library is for you if you are also annoyed that there is no mutable pathlib wrapper for use cases in which paths are often changed.
mutapath solves this by wrapping both, the Python 3 pathlib library, and the alternate [path library](https://pypi.org/project/path/), and providing a mutable context manager for them.
## MutaPath Class
The MutaPath Class allows direct mutation of its attributes at any time, just as any mutable object.
Once a file operation is called that is intended to modify its path, the underlying path is also mutated.
```python
>>> from mutapath import MutaPath
```
```python
>>> folder = MutaPath("/home/joe/doe/folder/sub")
>>> folder
Path('/home/joe/doe/folder/sub')
```
```python
>>> folder.name = "top"
>>> folder
Path('/home/joe/doe/folder/top')
```
```python
>>> next = MutaPath("/home/joe/doe/folder/next")
>>> next
Path('/home/joe/doe/folder/next')
```
```python
>>> next.rename(folder)
>>> next
Path('/home/joe/doe/folder/top')
>>> next.exists()
True
>>> Path('/home/joe/doe/folder/sub').exists()
False
```
## Path Class
This class is immutable by default, just as the `pathlib.Path`. However, it allows to open a editing context via `mutate()`.
Moreover, there are additional contexts for file operations. They update the file and its path while closing the context.
If the file operations don't succeed, they throw an exception and fall back to the original path value.
```python
>>> from mutapath import Path
```
```python
>>> folder = Path("/home/joe/doe/folder/sub")
>>> folder
Path('/home/joe/doe/folder/sub')
```
```python
>>> folder.name = "top"
AttributeError: mutapath.Path is an immutable class, unless mutate() context is used.
>>> folder
Path('/home/joe/doe/folder/sub')
```
```python
>>> with folder.mutate() as m:
... m.name = "top"
>>> folder
Path('/home/joe/doe/folder/top')
```
```python
>>> next = Path("/home/joe/doe/folder/next")
>>> next.copy(folder)
>>> next
Path('/home/joe/doe/folder/next')
>>> folder.exists()
True
>>> folder.remove()
```
```python
>>> with next.renaming() as m:
... m.stem = folder.stem
... m.suffix = ".txt"
>>> next
Path("/home/joe/doe/folder/sub.txt")
>>> next.exists()
True
>>> next.with_name("next").exists()
False
```
For more in-depth examples, check the tests folder.
## Locks
Soft Locks can easily be accessed via the lazy lock property.
Moreover, the mutable context managers in `Path` (i.e., `renaming`, `moving`, `copying`) allow implicit locking.
The lock object is cached as long as the file is not mutated.
Once the lock is mutated, it is released and regenerated, respecting the new file name.
```python
>>> my_path = Path('/home/doe/folder/sub')
>>> with my_path.lock:
... my_path.write_text("I can write")
```
## Hashing
mutapath paths are hashable by caching the generated hash the first time it is accessed.
However, it also adds a warning so that unintended hash usage is avoided.
Once mutated after that, the generated hashes don't provide collision detection in binary trees anymore.
Don't use them in sets or as keys in dicts.
Use the explicit string representation instead, to make the hashing input transparent.
```python
>>> p = Path("/home")
>>> hash(p)
1083235232
>>> hash(Path("/home")) == hash(p)
True
>>> with p.mutate() as m:
... m.name = "home4"
>>> hash(p) # same hash
1083235232
>>> hash(Path("/home")) == hash(p) # they are not equal anymore
True
```
Raw data
{
"_id": null,
"home_page": "https://mutapath.fax.fyi",
"name": "mutapath",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8,<4.0",
"maintainer_email": "",
"keywords": "pathlib,mutable,path",
"author": "matfax",
"author_email": "mat@fax.fyi",
"download_url": "https://files.pythonhosted.org/packages/e7/03/89b7833080a55ff812a5627a0e87b4fe703bb3f5a910c46eb28239ddd14f/mutapath-0.17.1.tar.gz",
"platform": null,
"description": "# mutapath\n\n[](https://github.com/matfax/mutapath/actions)\n[](https://codecov.io/gh/matfax/mutapath)\n[](https://mutapath.readthedocs.io/en/latest/?badge=latest)\n[](https://github.com/matfax/mutapath/issues/270)\n[](https://libraries.io/pypi/mutapath)\n[](https://www.codefactor.io/repository/github/matfax/mutapath)\n[](https://github.com/PyCQA/bandit)\n[](https://github.com/psf/black)\n[](https://pypi.org/project/mutapath/)\n[](https://pypi.org/project/mutapath/)\n[](https://pypistats.org/packages/mutapath)\n[](https://github.com/matfax/mutapath/releases)\n[](https://github.com/matfax/mutapath/commits/main)\n[](https://github.com/matfax/mutapath/blob/main/LICENSE)\n\nThis library is for you if you are also annoyed that there is no mutable pathlib wrapper for use cases in which paths are often changed.\nmutapath solves this by wrapping both, the Python 3 pathlib library, and the alternate [path library](https://pypi.org/project/path/), and providing a mutable context manager for them.\n\n## MutaPath Class\n\nThe MutaPath Class allows direct mutation of its attributes at any time, just as any mutable object.\nOnce a file operation is called that is intended to modify its path, the underlying path is also mutated.\n\n```python\n>>> from mutapath import MutaPath\n```\n```python\n>>> folder = MutaPath(\"/home/joe/doe/folder/sub\")\n>>> folder\nPath('/home/joe/doe/folder/sub')\n```\n```python\n>>> folder.name = \"top\"\n>>> folder\nPath('/home/joe/doe/folder/top')\n```\n```python\n>>> next = MutaPath(\"/home/joe/doe/folder/next\")\n>>> next\nPath('/home/joe/doe/folder/next')\n```\n```python\n>>> next.rename(folder)\n>>> next\nPath('/home/joe/doe/folder/top')\n>>> next.exists()\nTrue\n>>> Path('/home/joe/doe/folder/sub').exists()\nFalse\n```\n\n## Path Class\n\nThis class is immutable by default, just as the `pathlib.Path`. However, it allows to open a editing context via `mutate()`.\nMoreover, there are additional contexts for file operations. They update the file and its path while closing the context.\nIf the file operations don't succeed, they throw an exception and fall back to the original path value.\n\n```python\n>>> from mutapath import Path\n```\n```python\n>>> folder = Path(\"/home/joe/doe/folder/sub\")\n>>> folder\nPath('/home/joe/doe/folder/sub')\n```\n```python\n>>> folder.name = \"top\"\nAttributeError: mutapath.Path is an immutable class, unless mutate() context is used.\n>>> folder\nPath('/home/joe/doe/folder/sub')\n```\n```python\n>>> with folder.mutate() as m:\n... m.name = \"top\"\n>>> folder\nPath('/home/joe/doe/folder/top')\n```\n```python\n>>> next = Path(\"/home/joe/doe/folder/next\")\n>>> next.copy(folder)\n>>> next\nPath('/home/joe/doe/folder/next')\n>>> folder.exists()\nTrue\n>>> folder.remove()\n```\n```python\n>>> with next.renaming() as m:\n... m.stem = folder.stem\n... m.suffix = \".txt\"\n>>> next\nPath(\"/home/joe/doe/folder/sub.txt\")\n>>> next.exists()\nTrue\n>>> next.with_name(\"next\").exists()\nFalse\n```\n\nFor more in-depth examples, check the tests folder.\n\n## Locks\n\nSoft Locks can easily be accessed via the lazy lock property.\nMoreover, the mutable context managers in `Path` (i.e., `renaming`, `moving`, `copying`) allow implicit locking.\nThe lock object is cached as long as the file is not mutated. \nOnce the lock is mutated, it is released and regenerated, respecting the new file name.\n\n```python\n>>> my_path = Path('/home/doe/folder/sub')\n>>> with my_path.lock:\n... my_path.write_text(\"I can write\")\n```\n\n## Hashing\n\nmutapath paths are hashable by caching the generated hash the first time it is accessed.\nHowever, it also adds a warning so that unintended hash usage is avoided.\nOnce mutated after that, the generated hashes don't provide collision detection in binary trees anymore.\nDon't use them in sets or as keys in dicts.\nUse the explicit string representation instead, to make the hashing input transparent.\n\n```python\n>>> p = Path(\"/home\")\n>>> hash(p)\n1083235232\n>>> hash(Path(\"/home\")) == hash(p)\nTrue\n>>> with p.mutate() as m:\n... m.name = \"home4\"\n>>> hash(p) # same hash\n1083235232\n>>> hash(Path(\"/home\")) == hash(p) # they are not equal anymore\nTrue\n```\n",
"bugtrack_url": null,
"license": "LGPL-3.0",
"summary": "mutable pathlib",
"version": "0.17.1",
"project_urls": {
"Documentation": "https://mutapath.fax.fyi",
"Homepage": "https://mutapath.fax.fyi",
"Repository": "https://github.com/matfax/mutapath"
},
"split_keywords": [
"pathlib",
"mutable",
"path"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "5ebcf2fc0891bebd041e1ab3785ba3e14737dcd38ac2957f25fb8c3e45c78a09",
"md5": "1b3cb79a02945b2e9e85cedac1cfcaaf",
"sha256": "81833d71e3c63a3b48c8cc1c0a9e6529541e7e6c610629afb206cdd7376ef0ee"
},
"downloads": -1,
"filename": "mutapath-0.17.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1b3cb79a02945b2e9e85cedac1cfcaaf",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8,<4.0",
"size": 15200,
"upload_time": "2023-07-13T14:19:58",
"upload_time_iso_8601": "2023-07-13T14:19:58.159217Z",
"url": "https://files.pythonhosted.org/packages/5e/bc/f2fc0891bebd041e1ab3785ba3e14737dcd38ac2957f25fb8c3e45c78a09/mutapath-0.17.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "e70389b7833080a55ff812a5627a0e87b4fe703bb3f5a910c46eb28239ddd14f",
"md5": "d8f0cd08c8aa79f4e30a4a69c4f84253",
"sha256": "a36fbbc25fac3dd1e3bfbf63f566eef1771a54a9cfbfb11ae1b614b208bb7dd7"
},
"downloads": -1,
"filename": "mutapath-0.17.1.tar.gz",
"has_sig": false,
"md5_digest": "d8f0cd08c8aa79f4e30a4a69c4f84253",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8,<4.0",
"size": 16110,
"upload_time": "2023-07-13T14:19:59",
"upload_time_iso_8601": "2023-07-13T14:19:59.572658Z",
"url": "https://files.pythonhosted.org/packages/e7/03/89b7833080a55ff812a5627a0e87b4fe703bb3f5a910c46eb28239ddd14f/mutapath-0.17.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-07-13 14:19:59",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "matfax",
"github_project": "mutapath",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "mutapath"
}
JSON
