<img src="https://raw.githubusercontent.com/databio/yacman/master/docs/img/yacman_logo.svg?sanitize=true" alt="yacman" height="70"/><br>
[](https://codecov.io/gh/databio/yacman)
[](https://github.com/psf/black)
[](https://anaconda.org/conda-forge/yacman)
Yacman is a YAML configuration manager. It provides some convenience tools for dealing with YAML configuration files.
Please see [this](docs/usage.md) Python notebook for features and usage instructions and [this](docs/api_docs.md) document for API documentation.
## Upgrading guide
How to upgrade to yacman v1.0.0.
Yacman v1 provides 2 feature upgrades:
1. Constructors take the form of `yacman.YAMLConfigManager.from_x(...)` functions, to make it clearer how to
create a new `ym` object.
2. It separates locks into read locks and write locks, to allow mutliple simultaneous readers.
The v0.9.3 transition release would has versions, really:
- attmap-based version (YacAttMap)
- non-attmap-but-mostly-compatible (YAMLConfigManager)
- new future object (FutureYAMLConfigManager...), which is not-backwards-compatible.
In v1.0.0, FutureYAMLConfigManager will be renamed to YAMLConfigManager and the old stuff will be removed.
Here's how to transition your code:
### Use the FutureYAMLConfigManager in 0.9.3
1. Import the FutureYAMLConfigManager
Change from:
```
from yacman import YAMLConfigManager
```
to
```
from yacman import FutureYAMLConfigManager as YAMLConfigManager
```
Once we switch from `v0.9.3` to `v1.X.X`, you will need to switch back.
2. Update any context managers to use `write_lock` or `read_lock`
```
from yacman import write_lock, read_lock
```
Change
```
with ym as locked_ym:
locked_ym.write()
```
to
```
with write_lock(ym) as locked_ym:
locked_ym.write()
```
More examples:
```
from yacman import FutureYAMLConfigManager as YAMLConfigManager
data = {"my_list": [1,2,3], "my_int": 8, "my_str": "hello world!", "my_dict": {"nested_val": 15}}
ym = YAMLConfigManager(data)
ym["my_list"]
ym["my_int"]
ym["my_dict"]
# Use in a context manager to write to the file
ym["new_var"] = 15
with write(ym) as locked_ym:
locked_ym.rebase()
locked_ym.write()
with read(ym) as locked_ym:
locked_ym.rebase()
```
3. Update any constructors to use the `from_{x}` functions
You can no longer just create a `YAMLConfigManager` object directly; now you need to use the constructor helpers.
Examples:
```
from yacman import FutureYAMLConfigManager as YAMLConfigManager
data = {"my_list": [1,2,3], "my_int": 8, "my_str": "hello world!", "my_dict": {"nested_val": 15}}
file_path = "tests/data/full.yaml"
yaml_data = "myvar: myval"
yacman.YAMLConfigManager.from_yaml_file(file_path)
yacman.YAMLConfigManager.from_yaml_data(yaml_data)
yacman.YAMLConfigManager.from_obj(data)
```
In the past, you could load from a file and overwrite some attributes with a dict of variables, all from the constructor.
Now it would is more explicit:
```
ym = yacman.YacMan.from_yaml_file(file_path)
ym.update_from_obj(data)
```
To exppand environment variables in values, use `.exp`.
```
ym.exp["text_expand_home_dir"]
```
## From v0.9.3 (using future) to v1.X.X:
Switch back to:
```
from yacman import YAMLConfigManager
```
## Demos
Some interactive demos
```
from yacman import FutureYAMLConfigManager as YAMLConfigManager
ym = yacman.YAMLConfigManager(entries=["a", "b", "c"])
ym.to_dict()
ym
print(ym.to_yaml())
ym = YAMLConfigManager(entries={"top": {"bottom": ["a", "b"], "bottom2": "a"}, "b": "c"})
ym
print(ym.to_yaml())
ym = YAMLConfigManager(filepath="tests/data/conf_schema.yaml")
print(ym.to_yaml())
ym
ym = YAMLConfigManager(filepath="tests/data/empty.yaml")
print(ym.to_yaml())
ym = YAMLConfigManager(filepath="tests/data/list.yaml")
print(ym.to_yaml())
ym = YAMLConfigManager(YAMLConfigManager(filepath="tests/data/full.yaml").exp)
print(ym.to_yaml())
ym = YAMLConfigManager(filepath="tests/data/full.yaml")
print(ym.to_yaml(expand=True))
```
Raw data
{
"_id": null,
"home_page": "https://github.com/databio/yacman",
"name": "yacman",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "bioinformatics,sequencing,ngs",
"author": "Nathan Sheffield, Michal Stolarczyk",
"author_email": "nathan@code.databio.org",
"download_url": "https://files.pythonhosted.org/packages/e0/ff/df6069918146df382414e4b0b41a341c9207763d0ae31abc4dd538adbc83/yacman-0.9.3.tar.gz",
"platform": null,
"description": "<img src=\"https://raw.githubusercontent.com/databio/yacman/master/docs/img/yacman_logo.svg?sanitize=true\" alt=\"yacman\" height=\"70\"/><br>\n\n\n[](https://codecov.io/gh/databio/yacman)\n[](https://github.com/psf/black)\n[](https://anaconda.org/conda-forge/yacman)\n\nYacman is a YAML configuration manager. It provides some convenience tools for dealing with YAML configuration files.\n\nPlease see [this](docs/usage.md) Python notebook for features and usage instructions and [this](docs/api_docs.md) document for API documentation.\n\n## Upgrading guide\n\nHow to upgrade to yacman v1.0.0.\nYacman v1 provides 2 feature upgrades:\n\n1. Constructors take the form of `yacman.YAMLConfigManager.from_x(...)` functions, to make it clearer how to \ncreate a new `ym` object.\n2. It separates locks into read locks and write locks, to allow mutliple simultaneous readers.\n\nThe v0.9.3 transition release would has versions, really: \n- attmap-based version (YacAttMap)\n- non-attmap-but-mostly-compatible (YAMLConfigManager)\n- new future object (FutureYAMLConfigManager...), which is not-backwards-compatible.\n\nIn v1.0.0, FutureYAMLConfigManager will be renamed to YAMLConfigManager and the old stuff will be removed.\nHere's how to transition your code:\n\n### Use the FutureYAMLConfigManager in 0.9.3\n\n1. Import the FutureYAMLConfigManager\n\nChange from:\n\n```\nfrom yacman import YAMLConfigManager\n```\n\nto \n\n```\nfrom yacman import FutureYAMLConfigManager as YAMLConfigManager\n```\n\nOnce we switch from `v0.9.3` to `v1.X.X`, you will need to switch back.\n\n2. Update any context managers to use `write_lock` or `read_lock`\n\n```\nfrom yacman import write_lock, read_lock\n```\n\nChange\n\n```\nwith ym as locked_ym:\n\tlocked_ym.write()\n```\t\n\nto\n\n\n```\nwith write_lock(ym) as locked_ym:\n\tlocked_ym.write()\n```\n\n\n\nMore examples:\n\n```\n\nfrom yacman import FutureYAMLConfigManager as YAMLConfigManager\n\n\ndata = {\"my_list\": [1,2,3], \"my_int\": 8, \"my_str\": \"hello world!\", \"my_dict\": {\"nested_val\": 15}}\n\nym = YAMLConfigManager(data)\n\nym[\"my_list\"]\nym[\"my_int\"]\nym[\"my_dict\"]\n\n# Use in a context manager to write to the file\n\nym[\"new_var\"] = 15\n\nwith write(ym) as locked_ym:\n locked_ym.rebase()\n\tlocked_ym.write()\n\nwith read(ym) as locked_ym:\n\tlocked_ym.rebase()\n\n```\n\n\n\n\n3. Update any constructors to use the `from_{x}` functions\n\nYou can no longer just create a `YAMLConfigManager` object directly; now you need to use the constructor helpers.\n\nExamples:\n\n```\nfrom yacman import FutureYAMLConfigManager as YAMLConfigManager\n\ndata = {\"my_list\": [1,2,3], \"my_int\": 8, \"my_str\": \"hello world!\", \"my_dict\": {\"nested_val\": 15}}\nfile_path = \"tests/data/full.yaml\"\nyaml_data = \"myvar: myval\"\n\nyacman.YAMLConfigManager.from_yaml_file(file_path)\nyacman.YAMLConfigManager.from_yaml_data(yaml_data)\nyacman.YAMLConfigManager.from_obj(data)\n\n```\n\nIn the past, you could load from a file and overwrite some attributes with a dict of variables, all from the constructor.\nNow it would is more explicit:\n\n```\nym = yacman.YacMan.from_yaml_file(file_path)\nym.update_from_obj(data)\n```\n\nTo exppand environment variables in values, use `.exp`.\n\n```\nym.exp[\"text_expand_home_dir\"]\n```\n\n## From v0.9.3 (using future) to v1.X.X:\n\nSwitch back to: \n\n```\nfrom yacman import YAMLConfigManager\n```\n\n\n\n\n\n## Demos\n\nSome interactive demos\n\n```\nfrom yacman import FutureYAMLConfigManager as YAMLConfigManager\nym = yacman.YAMLConfigManager(entries=[\"a\", \"b\", \"c\"])\nym.to_dict()\nym\n\nprint(ym.to_yaml())\n\nym = YAMLConfigManager(entries={\"top\": {\"bottom\": [\"a\", \"b\"], \"bottom2\": \"a\"}, \"b\": \"c\"})\nym\nprint(ym.to_yaml())\n\nym = YAMLConfigManager(filepath=\"tests/data/conf_schema.yaml\")\nprint(ym.to_yaml())\nym\n\nym = YAMLConfigManager(filepath=\"tests/data/empty.yaml\")\nprint(ym.to_yaml())\n\nym = YAMLConfigManager(filepath=\"tests/data/list.yaml\")\nprint(ym.to_yaml())\n\nym = YAMLConfigManager(YAMLConfigManager(filepath=\"tests/data/full.yaml\").exp)\nprint(ym.to_yaml())\n\nym = YAMLConfigManager(filepath=\"tests/data/full.yaml\")\nprint(ym.to_yaml(expand=True))\n\n```\n",
"bugtrack_url": null,
"license": "BSD2",
"summary": "A standardized configuration object for reference genome assemblies",
"version": "0.9.3",
"project_urls": {
"Homepage": "https://github.com/databio/yacman"
},
"split_keywords": [
"bioinformatics",
"sequencing",
"ngs"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "07edd477d1df9728ac9f1af7c912e14da681d5b912024b930139e5a15ac0773e",
"md5": "5cbd6af693e8e8f63e8ae10a9595570d",
"sha256": "d77a3a05a58a0bcc993efc64c6b57a2265c1d1f11f65a8e31c71a1e3b8f0e144"
},
"downloads": -1,
"filename": "yacman-0.9.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5cbd6af693e8e8f63e8ae10a9595570d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 26240,
"upload_time": "2024-02-01T21:36:49",
"upload_time_iso_8601": "2024-02-01T21:36:49.830259Z",
"url": "https://files.pythonhosted.org/packages/07/ed/d477d1df9728ac9f1af7c912e14da681d5b912024b930139e5a15ac0773e/yacman-0.9.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "e0ffdf6069918146df382414e4b0b41a341c9207763d0ae31abc4dd538adbc83",
"md5": "f532c4d8f5965f77ed6c5107061494a9",
"sha256": "91f29ecad7abf32425be034619bd5b00a50fe2be23447b1827c34e1fd68c055d"
},
"downloads": -1,
"filename": "yacman-0.9.3.tar.gz",
"has_sig": false,
"md5_digest": "f532c4d8f5965f77ed6c5107061494a9",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 22714,
"upload_time": "2024-02-01T21:36:51",
"upload_time_iso_8601": "2024-02-01T21:36:51.675548Z",
"url": "https://files.pythonhosted.org/packages/e0/ff/df6069918146df382414e4b0b41a341c9207763d0ae31abc4dd538adbc83/yacman-0.9.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-02-01 21:36:51",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "databio",
"github_project": "yacman",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "yacman"
}
JSON
