| Name | sugaru JSON |
| Version |
0.3.1
JSON |
| download |
| home_page | |
| Summary | Create your own syntax stupidly simple! |
| upload_time | 2023-07-02 20:33:50 |
| maintainer | |
| docs_url | None |
| author | Dmitry Makarov |
| requires_python | >=3.7 |
| license | MIT |
| keywords |
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
<p align="center">
<a href="https://pypi.org/project/sugaru/"><img width="300px" src="https://github.com/Mityuha/sugaru/assets/17745407/4b25b429-620e-4718-8643-70b11cde0065" alt='sugaru'></a>
</p>
<p align="center">
<em>🍭 Your own syntax you've always been dreaming of. 🍭</em>
</p>
---
# Sugaru
Sugaru is a lightweight completely customizable plugin system,
that gives you an opportunity to do things like:
* Writing files followed your own syntax.
* Translating such files to ones with any other syntax.
* Any custom user-defined replacements (e.g. templates' replacements with environment variables).
* Converting files from one format to another (yaml --> json, toml --> ini, etc).
* Any other fascinating features you can imagine not listed above.
## Requirements
Python 3.7+
## Installation
```shell
$ pip3 install sugaru
```
## Table of contents
* [Quickstart](#quickstart)
* [How it actually works](#how-it-actually-works)
* [Preparations under the hood](#preparations-under-the-hood)
* [How objects are loaded](#how-objects-are-loaded)
* [Examples](#examples)
* [Dependencies](#dependencies)
* [Changelog](#changelog)
## Quickstart
It's better to see something once than to read documentation a thousand times. Let's follow this principle.
You are a kind of DevOps engineer. You write CI files every day. That's why you've learnt by heart some CI stages: literally, line-by-line.
One day you've fed up with copy-pasting/writing complete stages into the new project. And you have decided to reduce time and effort to write the same stage the hundredth time.
You took a close look to your stage once again:
```yaml
stages:
- tests
pytest:
stage: "tests"
image: "python:3.12.0"
before_script:
- poetry install
script:
- poetry run pytest
```
And came up with idea to simply remove it. Indeed, the presence of some `python-tests` stage can mean the same stage's code every time. Why not just generate such a stage then? You ended up with the syntax like:
```yaml
stages: ""
python-tests: "python:3.12.0"
```
That's it! Looks good, doesn't it?
To translate `python-tests` stage to `tests` one let's write a couple of plugins that will do the job.
The first one will generate `stages` section:
```python
from typing import Any, Dict, List
def generate_stages(section_name: str, section: Any, sections: Dict[str, Any]) -> List[str]:
if section_name != "stages":
return section
known_stages: Dict[str, str] = {"python-tests": "tests"}
try:
return [known_stages[stage] for stage in sections if stage != "stages"]
except KeyError as unknown_stage:
raise ValueError(f"Unknown stage: {unknown_stage}") from None
```
The second plugin will generate `python-tests` section:
```python
def generate_tests(section_name: str, section: Any) -> Dict[str, Any]:
if section_name != "python-tests":
return section
py_image: str = section
return {
"stage": "tests",
"image": py_image,
"before_script": ["poetry install"],
"script": ["poetry run pytest"],
}
```
Let's put our plugins into the file called `python_tests.py`. And put our awesome yml syntax into the file called `.my-gitlab-ci.yml`.
To make it work simply type:
```bash
$ python3 -m sugaru .my-gitlab-ci.yml --plugin python_tests
```
That's it. You will see the correct `.gitlab-ci.yml` syntax output on your screen.
<p align="left">
<img width="400px" src="https://github.com/Mityuha/sugaru/assets/17745407/b47f9353-1f95-4407-83fb-13fb18abfa91" alt='how-it-works-no-detail'>
</p>
This picture illustrates how sugaru works in a nutshell.
## How it actually works
There are some classes under the hood that work as a pipeline:
<p align="left">
<img width="400px" src="https://github.com/Mityuha/sugaru/assets/17745407/c94cda75-b50c-48d8-827b-62d50e9d94f3" alt='how-it-works'>
</p>
There is a file path as an entry point parameter (e.g. path to `.my-gitlab-ci.yml`). Then the output of every component is the input of the next component.
* File Loader
* Output: file content as any JSON type
* Section Encoder
* Output: sections, i.e. mapping section-name: section-content.
* Plugin Executor
* Output: sections after every plugin execution
* Section Decoder
* Output: file content as any JSON type
* File Writer
* Output: the file with the content (including stdout)
There is also an interesting component called Object Loader. We'll discuss it later.
## Preparations under the hood
There is the default implementation for every component listed above.
Instead of using default components, you can define your own ones.
If you do so, such components are loaded by Object Loader component.
<p align="left">
<img width="600px" src="https://github.com/Mityuha/sugaru/assets/17745407/f1c97b38-a469-4d72-900a-c02eff81f956" alt='components-loading'>
</p>
And what about the Object Loader component itself?
Actually, you can even implement a custom Object Loader component. Such the custom Object Loader will be loaded by default Object Loader first and then will *replace* the default one.
## How objects are loaded
All custom defined objects -- including user plugins -- are loaded by interfaces.
To implement your own component you have to implement the interface dedicated to it.
For example, to implement custom Section Encoder you have to implement the following interface:
```python
class SectionEncoder(Protocol):
def __call__(self, content: JSON) -> Dict[SecName, Section]:
...
```
The only exception is user Plugin. A plugin interface is defined as
```python
class Plugin(Protocol):
def __call__(
self,
*,
section: Section,
section_name: str,
sections: Mapping[SecName, Section],
) -> Section:
...
```
To implement a plugin you should define *any* combination of interfaces' parameters. For example the following implementation also fits:
```python
def empty_section(section_name: str) -> Any:
print(section_name)
return {}
```
The last thing you should known about interface's implementation is that type hints are not validated by sugaru (yet). It's up to you to use type hints for your own purposes.
Take a closer look to `interfaces.py` file for more interfaces' detail.
## Examples
You will find more examples with detail explanations inside [examples](https://github.com/Mityuha/sugaru/tree/main/examples) folder.
## Dependencies
Sugaru has some default dependencies, that are:
- [typer](https://typer.tiangolo.com/). Typer makes sugaru more convenient to use.
- [pyyaml](https://pyyaml.org/). Sugaru manages to deal with yaml files by default.
You can also install [loguru](https://loguru.readthedocs.io/en/stable/) for more beautiful logs.
## Changelog
You can see the release history here: https://github.com/Mityuha/sugaru/releases/
---
<p align="center"><i>Sugaru is <a href="https://github.com/Mityuha/sugaru/blob/main/LICENSE">MIT licensed</a> code.</p>
Raw data
{
"_id": null,
"home_page": "",
"name": "sugaru",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "",
"author": "Dmitry Makarov",
"author_email": "mit.makaroff@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/4a/3a/29f11eb68b19e7d6b5767f3a01398ceed24b6e70298e228064ee4ffba5b5/sugaru-0.3.1.tar.gz",
"platform": null,
"description": "\n<p align=\"center\">\n <a href=\"https://pypi.org/project/sugaru/\"><img width=\"300px\" src=\"https://github.com/Mityuha/sugaru/assets/17745407/4b25b429-620e-4718-8643-70b11cde0065\" alt='sugaru'></a>\n</p>\n<p align=\"center\">\n <em>\ud83c\udf6d Your own syntax you've always been dreaming of. \ud83c\udf6d</em>\n</p>\n\n---\n\n# Sugaru\n\nSugaru is a lightweight completely customizable plugin system,\nthat gives you an opportunity to do things like:\n\n* Writing files followed your own syntax.\n* Translating such files to ones with any other syntax.\n* Any custom user-defined replacements (e.g. templates' replacements with environment variables).\n* Converting files from one format to another (yaml --> json, toml --> ini, etc).\n* Any other fascinating features you can imagine not listed above.\n\n## Requirements\n\nPython 3.7+\n\n## Installation\n\n```shell\n$ pip3 install sugaru\n```\n\n## Table of contents\n * [Quickstart](#quickstart)\n * [How it actually works](#how-it-actually-works)\n * [Preparations under the hood](#preparations-under-the-hood)\n * [How objects are loaded](#how-objects-are-loaded)\n * [Examples](#examples)\n * [Dependencies](#dependencies)\n * [Changelog](#changelog)\n\n## Quickstart\nIt's better to see something once than to read documentation a thousand times. Let's follow this principle. \nYou are a kind of DevOps engineer. You write CI files every day. That's why you've learnt by heart some CI stages: literally, line-by-line. \nOne day you've fed up with copy-pasting/writing complete stages into the new project. And you have decided to reduce time and effort to write the same stage the hundredth time. \nYou took a close look to your stage once again:\n```yaml\nstages:\n - tests\n\npytest:\n stage: \"tests\"\n image: \"python:3.12.0\"\n before_script:\n - poetry install\n script:\n - poetry run pytest\n```\nAnd came up with idea to simply remove it. Indeed, the presence of some `python-tests` stage can mean the same stage's code every time. Why not just generate such a stage then? You ended up with the syntax like:\n```yaml\nstages: \"\"\npython-tests: \"python:3.12.0\"\n```\nThat's it! Looks good, doesn't it? \nTo translate `python-tests` stage to `tests` one let's write a couple of plugins that will do the job. \nThe first one will generate `stages` section:\n```python\nfrom typing import Any, Dict, List\n\n\ndef generate_stages(section_name: str, section: Any, sections: Dict[str, Any]) -> List[str]:\n if section_name != \"stages\":\n return section\n\n known_stages: Dict[str, str] = {\"python-tests\": \"tests\"}\n try:\n return [known_stages[stage] for stage in sections if stage != \"stages\"]\n except KeyError as unknown_stage:\n raise ValueError(f\"Unknown stage: {unknown_stage}\") from None\n```\nThe second plugin will generate `python-tests` section:\n```python\ndef generate_tests(section_name: str, section: Any) -> Dict[str, Any]:\n if section_name != \"python-tests\":\n return section\n\n py_image: str = section\n return {\n \"stage\": \"tests\",\n \"image\": py_image,\n \"before_script\": [\"poetry install\"],\n \"script\": [\"poetry run pytest\"],\n }\n```\nLet's put our plugins into the file called `python_tests.py`. And put our awesome yml syntax into the file called `.my-gitlab-ci.yml`. \nTo make it work simply type:\n```bash\n$ python3 -m sugaru .my-gitlab-ci.yml --plugin python_tests\n```\nThat's it. You will see the correct `.gitlab-ci.yml` syntax output on your screen. \n<p align=\"left\">\n <img width=\"400px\" src=\"https://github.com/Mityuha/sugaru/assets/17745407/b47f9353-1f95-4407-83fb-13fb18abfa91\" alt='how-it-works-no-detail'>\n</p>\nThis picture illustrates how sugaru works in a nutshell.\n\n## How it actually works\nThere are some classes under the hood that work as a pipeline: \n<p align=\"left\">\n <img width=\"400px\" src=\"https://github.com/Mityuha/sugaru/assets/17745407/c94cda75-b50c-48d8-827b-62d50e9d94f3\" alt='how-it-works'>\n</p>\nThere is a file path as an entry point parameter (e.g. path to `.my-gitlab-ci.yml`). Then the output of every component is the input of the next component.\n\n* File Loader \n * Output: file content as any JSON type\n* Section Encoder\n * Output: sections, i.e. mapping section-name: section-content.\n* Plugin Executor\n * Output: sections after every plugin execution\n* Section Decoder\n * Output: file content as any JSON type\n* File Writer\n * Output: the file with the content (including stdout)\n\nThere is also an interesting component called Object Loader. We'll discuss it later.\n\n## Preparations under the hood\nThere is the default implementation for every component listed above. \nInstead of using default components, you can define your own ones. \nIf you do so, such components are loaded by Object Loader component. \n\n<p align=\"left\">\n <img width=\"600px\" src=\"https://github.com/Mityuha/sugaru/assets/17745407/f1c97b38-a469-4d72-900a-c02eff81f956\" alt='components-loading'>\n</p>\n\nAnd what about the Object Loader component itself? \nActually, you can even implement a custom Object Loader component. Such the custom Object Loader will be loaded by default Object Loader first and then will *replace* the default one.\n\n## How objects are loaded\nAll custom defined objects -- including user plugins -- are loaded by interfaces. \nTo implement your own component you have to implement the interface dedicated to it. \nFor example, to implement custom Section Encoder you have to implement the following interface:\n```python\nclass SectionEncoder(Protocol):\n def __call__(self, content: JSON) -> Dict[SecName, Section]:\n ...\n```\nThe only exception is user Plugin. A plugin interface is defined as\n```python\nclass Plugin(Protocol):\n def __call__(\n self,\n *,\n section: Section,\n section_name: str,\n sections: Mapping[SecName, Section],\n ) -> Section:\n ...\n```\nTo implement a plugin you should define *any* combination of interfaces' parameters. For example the following implementation also fits:\n```python\ndef empty_section(section_name: str) -> Any:\n print(section_name)\n return {}\n```\nThe last thing you should known about interface's implementation is that type hints are not validated by sugaru (yet). It's up to you to use type hints for your own purposes. \nTake a closer look to `interfaces.py` file for more interfaces' detail.\n\n## Examples\nYou will find more examples with detail explanations inside [examples](https://github.com/Mityuha/sugaru/tree/main/examples) folder.\n\n## Dependencies\n\nSugaru has some default dependencies, that are:\n- [typer](https://typer.tiangolo.com/). Typer makes sugaru more convenient to use. \n- [pyyaml](https://pyyaml.org/). Sugaru manages to deal with yaml files by default.\n\nYou can also install [loguru](https://loguru.readthedocs.io/en/stable/) for more beautiful logs.\n\n## Changelog\nYou can see the release history here: https://github.com/Mityuha/sugaru/releases/\n\n---\n\n<p align=\"center\"><i>Sugaru is <a href=\"https://github.com/Mityuha/sugaru/blob/main/LICENSE\">MIT licensed</a> code.</p>\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Create your own syntax stupidly simple!",
"version": "0.3.1",
"project_urls": null,
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "ae1ab47d9b1442096ebadb8110afae9e413ff0c3fa4fa7d4de321c9d0fdaee27",
"md5": "2541bab7826fbac3630a4676e00da0ff",
"sha256": "f7574fe481be3e182793e81fe80b0a1b22b359047974498ba2c98362443ac867"
},
"downloads": -1,
"filename": "sugaru-0.3.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2541bab7826fbac3630a4676e00da0ff",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 18638,
"upload_time": "2023-07-02T20:33:48",
"upload_time_iso_8601": "2023-07-02T20:33:48.818865Z",
"url": "https://files.pythonhosted.org/packages/ae/1a/b47d9b1442096ebadb8110afae9e413ff0c3fa4fa7d4de321c9d0fdaee27/sugaru-0.3.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "4a3a29f11eb68b19e7d6b5767f3a01398ceed24b6e70298e228064ee4ffba5b5",
"md5": "196ee4307aa7fdb00c8a509258491df4",
"sha256": "d4d4afff79730e8830672d234e6302bedbed58c88ee6f6a6caaef34f2660c162"
},
"downloads": -1,
"filename": "sugaru-0.3.1.tar.gz",
"has_sig": false,
"md5_digest": "196ee4307aa7fdb00c8a509258491df4",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 14820,
"upload_time": "2023-07-02T20:33:50",
"upload_time_iso_8601": "2023-07-02T20:33:50.493154Z",
"url": "https://files.pythonhosted.org/packages/4a/3a/29f11eb68b19e7d6b5767f3a01398ceed24b6e70298e228064ee4ffba5b5/sugaru-0.3.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-07-02 20:33:50",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "sugaru"
}
