Skip to main content

Python 3 tools for creating markup documents.

Project description

Build Status Downloads Downloads Downloads

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:

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.

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.

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.

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:

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 type annotations.
  • mypy is used to type-check the codebase, submitted code should not produce typing errors. See this page for more information on mypy.
  • Small fixes can be submitted simply by creating a pull request.
  • Non-trivial changes should have an associated issue in the issue tracker that commits must reference (typically by adding #refs <issue-id> to the end of commit messages).
  • Please write tests 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, 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 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.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

markyp-0.2307.0.tar.gz (17.5 kB view details)

Uploaded Source

Built Distribution

markyp-0.2307.0-py3-none-any.whl (12.0 kB view details)

Uploaded Python 3

File details

Details for the file markyp-0.2307.0.tar.gz.

File metadata

  • Download URL: markyp-0.2307.0.tar.gz
  • Upload date:
  • Size: 17.5 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/4.0.2 CPython/3.11.4

File hashes

Hashes for markyp-0.2307.0.tar.gz
Algorithm Hash digest
SHA256 121c41ef13cb10dfd3f45ee361d8341f51607b2e8dc4a8c890943058a9dd63d1
MD5 4d4bc75bcafc702a19ac5a3664ae85f0
BLAKE2b-256 5e0dd294a7f63c37d25bd72eb0e58655c9c76c0ab9252bda6c9e340e107bffda

See more details on using hashes here.

File details

Details for the file markyp-0.2307.0-py3-none-any.whl.

File metadata

  • Download URL: markyp-0.2307.0-py3-none-any.whl
  • Upload date:
  • Size: 12.0 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/4.0.2 CPython/3.11.4

File hashes

Hashes for markyp-0.2307.0-py3-none-any.whl
Algorithm Hash digest
SHA256 6fd150f7504ad8f71c6e96b2bb7e8b2b771f0662d13821d93940f44a2434ff8c
MD5 6d105fc68245f4db002b2d7dfb88450d
BLAKE2b-256 57f40c6c6d501d45f5e1fd89334dbccda64399c8204f8bd316088c5d78fc395a

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page