[](https://travis-ci.org/volfpeter/markyp)
[](https://pepy.tech/project/markyp)
[](https://pepy.tech/project/markyp/month)
[](https://pepy.tech/project/markyp/week)
# markyp
Python 3 tools for creating markup documents.
## Installation
The project is listed on the Python Package Index, it can be installed simply by executing `pip install markyp`.
## General concepts
Element creation in `markyp` and its derivates usually works as follows:
- If an element can have children, then the positional arguments passed to the component become the children of the created element.
- If an element can have attributes, then keyword arguments that are not listed explicitly on the argument list (i.e. `**kwargs`) are turned into element attributes.
- Explicitly declared keyword arguments work as documented.
The markup defined by the created elements can be obtained by converting to root element to string (`str()`) or by using the root element's `markup` property.
## Getting started
Creating new `markyp` element types is typically as simple as deriving new classes with the right name from the base elements that are provided by the project. The following example shows the creation of some HTML elements:
```Python
from markyp import ElementType
from markyp.elements import Element, StringElement
class html(Element):
__slots__ = ()
def __str__(self) -> str:
return f"<!DOCTYPE html>\n{(super().__str__())}"
class head(Element):
__slots__ = ()
class body(Element):
__slots__ = ()
class title(StringElement):
__slots__ = ()
class p(Element):
__slots__ = ()
@property
def inline_children(self) -> bool:
return True
class code(StringElement):
__slots__ = ()
class ul(Element):
__slots__ = ()
class li(Element):
__slots__ = ()
```
Once you have defined the basic components that are required by your project, you can make document creation easier by creating higher order functions that convert your data into markup elements.
```Python
def create_unordered_list(*items: ElementType) -> ul:
"""Creates an unordered list from the received arguments."""
return ul(
*(li(item, class_="fancy-list-item", style="color:blue;") for item in items),
class_="fancy-list"
)
```
When everything is in place, a document can be created simply by instantiating the elements that make up the document. Notice that during element construction, positional arguments are treated as children elements and keyword arguments are treated as element attributes, allowing you to create documents using a markup-like syntax.
```Python
document = html(
head(title("Hello World!")),
body(
p(code("markyp"), "HTML example.", style="font-weight:bold;"),
p("Creating lists is easy as", style="color:blue;"),
create_unordered_list("One", p("Two", style="font-style:italic;"), "Three"),
style="font-size:20px"
)
)
```
At this point, you have a Python object representing your document. The actual markup is created only when you convert this object into a string using either the `str()` method or the `markup` property of the element.
```Python
print(document)
```
## Domain-specific `markyp` extensions
`markyp` extensions should follow the `markyp-{domain-or-extension-name}` naming convention. Here is a list of domain-specific extensions:
- `markyp-rss`: RSS 2 implementation at https://github.com/volfpeter/markyp-rss, contribution is welcome.
- `markyp-html`: HTML implementation at https://github.com/volfpeter/markyp-html, contribution is welcome.
- `markyp-highlightjs`: HTML code highlighting using `highlight.js` at https://github.com/volfpeter/markyp-highlightjs, contribution is welcome.
- `markyp-bootstrap4`: Bootstrap 4 implementation at https://github.com/volfpeter/markyp-bootstrap4, contribution is welcome.
- `markyp-fontawesome`: Font Awesome icons for `markyp-html`-based web pages at https://github.com/volfpeter/markyp-fontawesome, contribution is welcome.
If you have created an open source `markyp` extension, please let us know and we will include your project in this list.
## Community guidelines
In general, please treat each other with respect and follow the below guidelines to interact with the project:
- _Questions, feedback_: Open an issue with a `[Question] <issue-title>` title.
- _Bug reports_: Open an issue with a `[Bug] <issue-title>` title, an adequate description of the bug, and a code snippet that reproduces the issue if possible.
- _Feature requests and ideas_: Open an issue with an `[Enhancement] <issue-title>` title and a clear description of the enhancement proposal.
## Contribution guidelines
Every form of contribution is welcome, including documentation improvements, tests, bug fixes, and feature implementations.
Please follow these guidelines to contribute to the project:
- Make sure your changes match the documentation and coding style of the project, including [PEP 484](https://www.python.org/dev/peps/pep-0484/) type annotations.
- `mypy` is used to type-check the codebase, submitted code should not produce typing errors. See [this page](http://mypy-lang.org/) for more information on `mypy`.
- _Small_ fixes can be submitted simply by creating a pull request.
- Non-trivial changes should have an associated [issue](#community-guidelines) in the issue tracker that commits must reference (typically by adding `#refs <issue-id>` to the end of commit messages).
- Please write [tests](#testing) for the changes you make (if applicable).
If you have any questions about contributing to the project, please contact the project owner.
## Testing
As mentioned in the [contribution guidelines](#contribution-guidelines), the project is type-checked using `mypy`, so first of all, the project must pass `mypy`'s static code analysis.
The project is tested using `pytest`. The chosen test layout is that tests are outside the application code, see [this page](https://docs.pytest.org/en/latest/goodpractices.html#tests-outside-application-code) for details on what it means in practice.
If `pytest` is installed, the test set can be executed using the `pytest test` command from within the project directory.
If `pytest-cov` is also installed, a test coverage report can be generated by executing `pytest test --cov markyp` from the root directory of the project.
## License - MIT
The library is open-sourced under the conditions of the MIT [license](https://choosealicense.com/licenses/mit/).
Raw data
{
"_id": null,
"home_page": "https://github.com/volfpeter/markyp",
"name": "markyp",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "markup generator utility xml html rss",
"author": "Peter Volf",
"author_email": "do.volfp@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/5e/0d/d294a7f63c37d25bd72eb0e58655c9c76c0ab9252bda6c9e340e107bffda/markyp-0.2307.0.tar.gz",
"platform": null,
"description": "[](https://travis-ci.org/volfpeter/markyp)\n[](https://pepy.tech/project/markyp)\n[](https://pepy.tech/project/markyp/month)\n[](https://pepy.tech/project/markyp/week)\n\n# markyp\n\nPython 3 tools for creating markup documents.\n\n## Installation\n\nThe project is listed on the Python Package Index, it can be installed simply by executing `pip install markyp`.\n\n## General concepts\n\nElement creation in `markyp` and its derivates usually works as follows:\n\n- If an element can have children, then the positional arguments passed to the component become the children of the created element.\n- If an element can have attributes, then keyword arguments that are not listed explicitly on the argument list (i.e. `**kwargs`) are turned into element attributes.\n- Explicitly declared keyword arguments work as documented.\n\nThe markup defined by the created elements can be obtained by converting to root element to string (`str()`) or by using the root element's `markup` property.\n\n## Getting started\n\nCreating new `markyp` element types is typically as simple as deriving new classes with the right name from the base elements that are provided by the project. The following example shows the creation of some HTML elements:\n\n```Python\nfrom markyp import ElementType\nfrom markyp.elements import Element, StringElement\n\nclass html(Element):\n __slots__ = ()\n\n def __str__(self) -> str:\n return f\"<!DOCTYPE html>\\n{(super().__str__())}\"\n\nclass head(Element):\n __slots__ = ()\n\nclass body(Element):\n __slots__ = ()\n\nclass title(StringElement):\n __slots__ = ()\n\nclass p(Element):\n __slots__ = ()\n\n @property\n def inline_children(self) -> bool:\n return True\n\nclass code(StringElement):\n __slots__ = ()\n\nclass ul(Element):\n __slots__ = ()\n\nclass li(Element):\n __slots__ = ()\n```\n\nOnce you have defined the basic components that are required by your project, you can make document creation easier by creating higher order functions that convert your data into markup elements.\n\n```Python\ndef create_unordered_list(*items: ElementType) -> ul:\n \"\"\"Creates an unordered list from the received arguments.\"\"\"\n return ul(\n *(li(item, class_=\"fancy-list-item\", style=\"color:blue;\") for item in items),\n class_=\"fancy-list\"\n )\n```\n\nWhen everything is in place, a document can be created simply by instantiating the elements that make up the document. Notice that during element construction, positional arguments are treated as children elements and keyword arguments are treated as element attributes, allowing you to create documents using a markup-like syntax.\n\n```Python\ndocument = html(\n head(title(\"Hello World!\")),\n body(\n p(code(\"markyp\"), \"HTML example.\", style=\"font-weight:bold;\"),\n p(\"Creating lists is easy as\", style=\"color:blue;\"),\n create_unordered_list(\"One\", p(\"Two\", style=\"font-style:italic;\"), \"Three\"),\n style=\"font-size:20px\"\n )\n)\n```\n\nAt this point, you have a Python object representing your document. The actual markup is created only when you convert this object into a string using either the `str()` method or the `markup` property of the element.\n\n```Python\nprint(document)\n```\n\n## Domain-specific `markyp` extensions\n\n`markyp` extensions should follow the `markyp-{domain-or-extension-name}` naming convention. Here is a list of domain-specific extensions:\n\n- `markyp-rss`: RSS 2 implementation at https://github.com/volfpeter/markyp-rss, contribution is welcome.\n- `markyp-html`: HTML implementation at https://github.com/volfpeter/markyp-html, contribution is welcome.\n- `markyp-highlightjs`: HTML code highlighting using `highlight.js` at https://github.com/volfpeter/markyp-highlightjs, contribution is welcome.\n- `markyp-bootstrap4`: Bootstrap 4 implementation at https://github.com/volfpeter/markyp-bootstrap4, contribution is welcome.\n- `markyp-fontawesome`: Font Awesome icons for `markyp-html`-based web pages at https://github.com/volfpeter/markyp-fontawesome, contribution is welcome.\n\nIf you have created an open source `markyp` extension, please let us know and we will include your project in this list.\n\n## Community guidelines\n\nIn general, please treat each other with respect and follow the below guidelines to interact with the project:\n\n- _Questions, feedback_: Open an issue with a `[Question] <issue-title>` title.\n- _Bug reports_: Open an issue with a `[Bug] <issue-title>` title, an adequate description of the bug, and a code snippet that reproduces the issue if possible.\n- _Feature requests and ideas_: Open an issue with an `[Enhancement] <issue-title>` title and a clear description of the enhancement proposal.\n\n## Contribution guidelines\n\nEvery form of contribution is welcome, including documentation improvements, tests, bug fixes, and feature implementations.\n\nPlease follow these guidelines to contribute to the project:\n\n- Make sure your changes match the documentation and coding style of the project, including [PEP 484](https://www.python.org/dev/peps/pep-0484/) type annotations.\n- `mypy` is used to type-check the codebase, submitted code should not produce typing errors. See [this page](http://mypy-lang.org/) for more information on `mypy`.\n- _Small_ fixes can be submitted simply by creating a pull request.\n- Non-trivial changes should have an associated [issue](#community-guidelines) in the issue tracker that commits must reference (typically by adding `#refs <issue-id>` to the end of commit messages).\n- Please write [tests](#testing) for the changes you make (if applicable).\n\nIf you have any questions about contributing to the project, please contact the project owner.\n\n## Testing\n\nAs mentioned in the [contribution guidelines](#contribution-guidelines), the project is type-checked using `mypy`, so first of all, the project must pass `mypy`'s static code analysis.\n\nThe project is tested using `pytest`. The chosen test layout is that tests are outside the application code, see [this page](https://docs.pytest.org/en/latest/goodpractices.html#tests-outside-application-code) for details on what it means in practice.\n\nIf `pytest` is installed, the test set can be executed using the `pytest test` command from within the project directory.\n\nIf `pytest-cov` is also installed, a test coverage report can be generated by executing `pytest test --cov markyp` from the root directory of the project.\n\n## License - MIT\n\nThe library is open-sourced under the conditions of the MIT [license](https://choosealicense.com/licenses/mit/).\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Python 3 tools for creating markup documents.",
"version": "0.2307.0",
"project_urls": {
"Homepage": "https://github.com/volfpeter/markyp"
},
"split_keywords": [
"markup",
"generator",
"utility",
"xml",
"html",
"rss"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "57f40c6c6d501d45f5e1fd89334dbccda64399c8204f8bd316088c5d78fc395a",
"md5": "6d105fc68245f4db002b2d7dfb88450d",
"sha256": "6fd150f7504ad8f71c6e96b2bb7e8b2b771f0662d13821d93940f44a2434ff8c"
},
"downloads": -1,
"filename": "markyp-0.2307.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "6d105fc68245f4db002b2d7dfb88450d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 11970,
"upload_time": "2023-06-30T15:09:08",
"upload_time_iso_8601": "2023-06-30T15:09:08.918060Z",
"url": "https://files.pythonhosted.org/packages/57/f4/0c6c6d501d45f5e1fd89334dbccda64399c8204f8bd316088c5d78fc395a/markyp-0.2307.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "5e0dd294a7f63c37d25bd72eb0e58655c9c76c0ab9252bda6c9e340e107bffda",
"md5": "4d4bc75bcafc702a19ac5a3664ae85f0",
"sha256": "121c41ef13cb10dfd3f45ee361d8341f51607b2e8dc4a8c890943058a9dd63d1"
},
"downloads": -1,
"filename": "markyp-0.2307.0.tar.gz",
"has_sig": false,
"md5_digest": "4d4bc75bcafc702a19ac5a3664ae85f0",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 17486,
"upload_time": "2023-06-30T15:09:10",
"upload_time_iso_8601": "2023-06-30T15:09:10.648969Z",
"url": "https://files.pythonhosted.org/packages/5e/0d/d294a7f63c37d25bd72eb0e58655c9c76c0ab9252bda6c9e340e107bffda/markyp-0.2307.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-06-30 15:09:10",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "volfpeter",
"github_project": "markyp",
"travis_ci": true,
"coveralls": false,
"github_actions": false,
"requirements": [],
"lcname": "markyp"
}
JSON
