| Name | sigils JSON |
| Version |
0.3.4
JSON |
| download |
| home_page | |
| Summary | Interpolate with %[sigils]. |
| upload_time | 2023-07-16 06:25:17 |
| maintainer | |
| docs_url | None |
| author | |
| requires_python | >=3.9 |
| license | MIT |
| keywords |
utils
sigils
string
text
context
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
================
Sigils
================
"An inscribed or painted symbol considered to have magical power."
Sigils is a Python library for magic and string interpolation. It provides advanced capabilities such as context-based interpolation, function execution, nested and recursive interpolation, case-insensitive matching, and global context support.
Any Python object can be provided as context, including nested dictionaries, lists, and functions. Sigils can be used directly from Python or from the command line. Sigils is thread-safe and has no dependencies outside of the Python standard library.
Installation
============
Install Sigils using pip:
.. code-block:: bash
pip install sigils
Usage
=====
Here's a simple example of using Sigils:
.. code-block:: python
from sigils import Sigil
context = {"user": {"name": "Alice"}}
s = Sigil("Hello, %[user.name]!")
print(s % context) # Outputs: Hello, Alice!
Sigils can handle function execution and nested interpolation:
.. code-block:: python
from sigils import Sigil
context = {
"user": {
"name": "Alice",
"greet": lambda name: f"Hello, {name}!"
}
}
s = Sigil("%[user.greet:user.name]")
print(s % context) # Outputs: Hello, Alice!
s = Sigil("%[user.greet:%%user.name]")
print(s % context) # Outputs: Hello, %user.name! %user.name is treated as a literal value
Sigils support case-insensitive matching and global context fallback:
.. code-block:: python
from sigils import Sigil, Sigil.Context
global_context = {"greeting": "Hello, world!"}
with Sigil.Context(global_context):
s = Sigil("%[GREETING]")
print(s % {}) # Outputs: Hello, world!
Command-Line Usage
==================
Sigils can be used directly from the command line. Here's an example:
.. code-block:: bash
sigils "Hello, %[user.name]!" -c context.json
In this example, "context.json" is a JSON file with a structure like {"user": {"name": "Alice"}}. The command will output: "Hello, Alice!".
Considerations
==============
- **Function Execution**: If the value of a Sigil is a callable function, it will be executed and its return value used in the string. Ensure all function values in your context are safe to execute.
- **Recursion Depth**: Sigils handles up to 6 levels of nested interpolation by default. Adjust this limit by passing a different `max_depth` value to the `interpolate` method.
- **Thread Safety**: The global context in Sigils is thread-safe. However, if you're using mutable objects in your context and modifying them from multiple threads, manage thread safety at the application level.
- **Case-Insensitive Matching**: If a key fails to resolve, a case-insensitive lookup is attempted. This only works if the keys in your context are all unique when lowercased.
Performance
===========
Sigils is designed with performance in mind. In typical use cases, Sigils performs competitively with Python's built-in string formatting.
License
=======
Sigils is licensed under the MIT License. See the LICENSE file for details.
Raw data
{
"_id": null,
"home_page": "",
"name": "sigils",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": "",
"keywords": "utils,sigils,string,text,context",
"author": "",
"author_email": "Rafael Jes\u00fas Guill\u00e9n Osorio <arthexis@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/75/f6/faa0de766151a46f42472de78ddf8f6e19a39d0023230150c935fe7bc968/sigils-0.3.4.tar.gz",
"platform": null,
"description": "================\r\nSigils\r\n================\r\n\r\n\"An inscribed or painted symbol considered to have magical power.\"\r\n\r\nSigils is a Python library for magic and string interpolation. It provides advanced capabilities such as context-based interpolation, function execution, nested and recursive interpolation, case-insensitive matching, and global context support.\r\n\r\nAny Python object can be provided as context, including nested dictionaries, lists, and functions. Sigils can be used directly from Python or from the command line. Sigils is thread-safe and has no dependencies outside of the Python standard library.\r\n\r\nInstallation\r\n============\r\n\r\nInstall Sigils using pip:\r\n\r\n.. code-block:: bash\r\n\r\n pip install sigils\r\n\r\nUsage\r\n=====\r\n\r\nHere's a simple example of using Sigils:\r\n\r\n.. code-block:: python\r\n\r\n from sigils import Sigil\r\n\r\n context = {\"user\": {\"name\": \"Alice\"}}\r\n s = Sigil(\"Hello, %[user.name]!\")\r\n print(s % context) # Outputs: Hello, Alice!\r\n\r\nSigils can handle function execution and nested interpolation:\r\n\r\n.. code-block:: python\r\n\r\n from sigils import Sigil\r\n\r\n context = {\r\n \"user\": {\r\n \"name\": \"Alice\",\r\n \"greet\": lambda name: f\"Hello, {name}!\"\r\n }\r\n }\r\n \r\n s = Sigil(\"%[user.greet:user.name]\")\r\n print(s % context) # Outputs: Hello, Alice!\r\n\r\n s = Sigil(\"%[user.greet:%%user.name]\")\r\n print(s % context) # Outputs: Hello, %user.name! %user.name is treated as a literal value\r\n\r\nSigils support case-insensitive matching and global context fallback:\r\n\r\n.. code-block:: python\r\n\r\n from sigils import Sigil, Sigil.Context\r\n\r\n global_context = {\"greeting\": \"Hello, world!\"}\r\n with Sigil.Context(global_context):\r\n s = Sigil(\"%[GREETING]\")\r\n print(s % {}) # Outputs: Hello, world!\r\n\r\nCommand-Line Usage\r\n==================\r\n\r\nSigils can be used directly from the command line. Here's an example:\r\n\r\n.. code-block:: bash\r\n\r\n sigils \"Hello, %[user.name]!\" -c context.json\r\n\r\nIn this example, \"context.json\" is a JSON file with a structure like {\"user\": {\"name\": \"Alice\"}}. The command will output: \"Hello, Alice!\".\r\n\r\nConsiderations\r\n==============\r\n\r\n- **Function Execution**: If the value of a Sigil is a callable function, it will be executed and its return value used in the string. Ensure all function values in your context are safe to execute.\r\n- **Recursion Depth**: Sigils handles up to 6 levels of nested interpolation by default. Adjust this limit by passing a different `max_depth` value to the `interpolate` method.\r\n- **Thread Safety**: The global context in Sigils is thread-safe. However, if you're using mutable objects in your context and modifying them from multiple threads, manage thread safety at the application level.\r\n- **Case-Insensitive Matching**: If a key fails to resolve, a case-insensitive lookup is attempted. This only works if the keys in your context are all unique when lowercased.\r\n\r\nPerformance\r\n===========\r\n\r\nSigils is designed with performance in mind. In typical use cases, Sigils performs competitively with Python's built-in string formatting.\r\n\r\nLicense\r\n=======\r\n\r\nSigils is licensed under the MIT License. See the LICENSE file for details.\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Interpolate with %[sigils].",
"version": "0.3.4",
"project_urls": {
"Bug-Tracker": "https://github.com/arthexis/sigils/issues",
"Source": "https://github.com/arthexis/sigils"
},
"split_keywords": [
"utils",
"sigils",
"string",
"text",
"context"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "3d34c0b7e407496297d79273a40386dba557b60f14f139745d52c8b5b942ee04",
"md5": "b13b1db8333c9fb6825e2c9062d83a06",
"sha256": "188362f91d7bc2e22bea5b9751203eb5be7d2a14f84356b59da86e23867ec1d5"
},
"downloads": -1,
"filename": "sigils-0.3.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b13b1db8333c9fb6825e2c9062d83a06",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 7249,
"upload_time": "2023-07-16T06:25:15",
"upload_time_iso_8601": "2023-07-16T06:25:15.824853Z",
"url": "https://files.pythonhosted.org/packages/3d/34/c0b7e407496297d79273a40386dba557b60f14f139745d52c8b5b942ee04/sigils-0.3.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "75f6faa0de766151a46f42472de78ddf8f6e19a39d0023230150c935fe7bc968",
"md5": "0271a5d6043efbabea1e21b411de74d8",
"sha256": "15c204b214eafa38ebd4d28d8cd3828c5a2bba0689a024d41c043c6b799ffe1d"
},
"downloads": -1,
"filename": "sigils-0.3.4.tar.gz",
"has_sig": false,
"md5_digest": "0271a5d6043efbabea1e21b411de74d8",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 9361,
"upload_time": "2023-07-16T06:25:17",
"upload_time_iso_8601": "2023-07-16T06:25:17.023007Z",
"url": "https://files.pythonhosted.org/packages/75/f6/faa0de766151a46f42472de78ddf8f6e19a39d0023230150c935fe7bc968/sigils-0.3.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-07-16 06:25:17",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "arthexis",
"github_project": "sigils",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"tox": true,
"lcname": "sigils"
}
