libzet


Namelibzet JSON
Version 2.2.5 PyPI version JSON
download
home_page
SummaryPython3 library for zettel reading.
upload_time2024-02-04 03:48:32
maintainer
docs_urlNone
author
requires_python<4,>=3.7
licenseGPLv2
keywords
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            ========
 libzet
========
Hello and welcome to libzet, a library for managing zettels.

Building and installation
=========================
Available from PyPi; Just ``pip3 install libzet``

Alternatively, clone this repo and then pip3 install.

::

    pip3 install --user .

Testing
=======
Use the following command to run unit tests.

::

    python3 -m unittest

Maintenance and versioning
==========================
Update the CHANGELOG and version in pyproject.toml when cutting a release.
Build with ``make`` and use ``make release`` to upload to pypi.

Usage
=====
The libzet library provides functions to parse zettels out of Markdown
or RST text formats and manage these zettels on the filesystem.

Zettel File Format
------------------
Zettels may be stored in markdown or RST format. Each may have a title,
content, and metadata in yaml format. The metadata is stored at the bottom
because metadata blocks can grow quite large.

Here's an example in markdown.

::

    # Markdown Zettel Title

    Some content

    ## Heading 1
    Notes under Heading 1

    <!--- attributes --->
        ---
        creation_date: 2023-03-09
        zlinks: {}

And an example in RST.

::
    
    ==================
     RST Zettel Title
    ==================
    Some content

    Heading 1
    =========
    Notes under Heading 1

    .. attributes
    ::

        ---
        creation_date: 2023-03-09
        zlinks: {}

Zettel Class
------------
Text formatted as above may be parsed into Zettel objects.

- ``zettel.title``: Title of the zettel.
- ``zettel.headings``: Dictionary of level-2 headings within the zettel. The
  content immediately under the title is in the ``_notes`` key.
- ``zettel.attrs``: Attributes of the Zettel.

The ``attrs`` is a dictionary that will automatically parse date fields. Any
key with the word 'date' in it will be parsed. Dates read in this matter may
be very free-form. Plain English phrases such as "tomorrow" or
"next Wednesday" should work fine.

Parsing and printing
--------------------
Zettels can be parsed out of a string with the ``str_to_zettels`` function, and
then printed using the ``zettels_to_str`` function or the zettel's own
``getMd()`` or ``getRst()`` methods.

::

    def str_to_zettels(text, zettel_format):
        """ Convert a str to a list of zettels.
    
        This function's return may be passed to zettels_to_str.
    
        Args:
            text: Text to convert to zettels.
            zettel_format: 'rst' or 'md'.
    
        Returns:
            A list of Zettel references.
    
        Raises:
            ValueError if the text was invalid.
        """
    
    
    def zettels_to_str(zettels, zettel_format, headings=None):
        """ Return many zettels as a str.
    
        This function's return may be passed to str_to_zettels.
    
        Args:
            zettels: List of zettels to print.
            zettel_format: 'rst' or 'md'.
            headings: Only print select headings.
    
        Returns:
            A str representing the zettels.
        """

Filesystem management
---------------------
Libzet provides functions to assist with managing zettels on the filesystem.

- Create a new zettel on disk with ``create_zettel``
- Load a list of zettels from disk with ``load_zettels``
- Filter this list based on the needs of your application.
- Modify the zettels and save the changes with ``save_zettels``
- Or send them to ``edit_zettels`` to edit them in a text editor.
- Move zettels around using ``copy_zettels`` or ``move_zettels``
- Remove unwanted zettels with ``delete_zettels``

These functions each return valid zettel references with respect to their
locations on disk. The general idea for an application is to keep track
of its zettels using the return values of these functions.

A zettel's location on disk is tracked with a ``_loadpath`` attribute. These
functions will automatically manage this attribute, so ensure it is not
carelessly modified in flight.

::

    def create_zettel(
            path,
            text='', title='', headings=None, attrs=None, zettel_format='md',
            no_edit=False, errlog='', template=None):
        """ Create and new zettel on disk and edit it.
    
        Args:
            path: Path to create new zettel.
            text: Provide a body of text from which to parse the whole zettel.
            headings: Headings to create the new zettel with.
            attrs: Default attributes to create the zettel.
            zettel_format: 'md' or 'rst'
            errlog: See edit_zettels
            no_edit: Set to True to skip editing.
            template: Optionally init the new zettel from a template. May be
                a path to a yaml file or a dict. Defaults to ztemplate.yaml
                within the same dir as the new zettel.
    
                If template exists then the headings and attrs from that
                file will be used to init the zettel.
    
        Returns:
            The new zettel reference.
    
        Raises:
            FileExistsError: There was already a zettel at path.
            ValueError: The newly created zettel was invalid.
        """
    
    
    def load_zettels(paths, zettel_format='md', recurse=False):
        """ Load Zettels from the filesystem.
    
        Zettels will be updated with a _loadpath value in their attrs.
        Send these zettels to save_zettels after modifying them to write
        them to disk. The _loadpath attribute will not be written to disk.
    
        Args:
            paths: Path or list paths to zettels. Each may be a dir or file.
            zettel_format: md or rst
            recurse: True to recurse into subdirs, False otherwise.
    
        Returns:
            A list of zettels.
    
            This list may be passed to save_zettels to write
            them to the filesystem.
    
        Raises:
            OSError if one of the files couldn't be opened.
            ValueError if one of the zettels contained invalid text.
        """
    
    
    def edit_zettels(zettels, zettel_format='md', headings=None, errlog='', delete=False):
        """ Bulk edit zettels provided by load_zettels.
    
        Delete the text for a zettel to avoid updating it.
    
        It is possible to add new zettels while editing, just be sure
        to set the _loadpath attribute for each new zettel.
    
        Args:
            zettels: List of zettels to edit.
            zettel_format: md or rst.
            headings: Only edit specific headings for each zettel.
            errlog: Write your working text to this location if parsing failed.
            delete: If True, then zettels whose text is deleted during editing will
                also be deleted from the disk.
    
        Returns:
            A list of zettels that were updated. Deleted zettels will not be
            in this list.
    
        Raises:
            ValueError if any zettels were edited in an invalid way.
        """
    
    
    def save_zettels(zettels, zettel_format='md'):
        """ Save zettels back to disk.

        the _loadpath attribute will not be written.
    
        Args:
            zettels: List of zettels.
            zettel_format: md or rst.
    
        Returns:
            The list of zettels as saved to disk.
    
        Raises:
            KeyError if a zettel is missing a _loadpath attribute. No zettels
                will be written to disk if this is the case.
    
            OSError if a zettel's text couldn't be written to disk.
        """
    
    
    def delete_zettels(zettels):
        """ Delete zettels from the filesystem.
    
        Args:
            zettels: Zettels to delete. Must have a _loadpath attribute.
    
        Returns:
            An empty list to represent the loss of these zettels
    
        Raises:
            KeyError if any zettels were missing a _loadpath. No zettels
                will be deleted in this case.
    
            OSError if the zettel could not be deleted.
        """
    
    
    def copy_zettels(zettels, dest, zettel_format='md'):
        """ Copy zettels to a new file location.
    
        Zettels are saved to disk before copying.
    
        Args:
            zettels: List of zettels to copy.
            zettel_format: md or rst.
            dest: Location to copy them to.
    
        Returns:
            A list of the new zettels loaded from their new file locations.
    
        Raises:
            KeyError if any zettels were missing a _loadpath. No zettels
                will be written to disk in this case.
    
            OSError if any of the zettels failed to copy.
    
            See shutil.copy
        """
    
    
    def move_zettels(zettels, dest, zettel_format='md'):
        """ Move zettels. Zettels will be saved before moving.

        The zettels will be deleted from their former paths which
        invalidates their previous _loadpath. Use this function like...

            zettels = move_zettels(zettels, './new-dir/')
    
        Args:
            zettels: List of zettels to move.
            zettel_format: md or rst.
            dest: Destination directory.
    
        Returns:
            A list of the zettels from their new home.
    
        Raises:
            See copy_zettels and delete_zettels.
        """

            

Raw data

            {
    "_id": null,
    "home_page": "",
    "name": "libzet",
    "maintainer": "",
    "docs_url": null,
    "requires_python": "<4,>=3.7",
    "maintainer_email": "",
    "keywords": "",
    "author": "",
    "author_email": "OneRedDime <onereddime@protonmail.com>",
    "download_url": "https://files.pythonhosted.org/packages/2a/a4/60a531d8910f149bd22e151f100979f86e90913d5cd130b173428ccb76ec/libzet-2.2.5.tar.gz",
    "platform": null,
    "description": "========\n libzet\n========\nHello and welcome to libzet, a library for managing zettels.\n\nBuilding and installation\n=========================\nAvailable from PyPi; Just ``pip3 install libzet``\n\nAlternatively, clone this repo and then pip3 install.\n\n::\n\n    pip3 install --user .\n\nTesting\n=======\nUse the following command to run unit tests.\n\n::\n\n    python3 -m unittest\n\nMaintenance and versioning\n==========================\nUpdate the CHANGELOG and version in pyproject.toml when cutting a release.\nBuild with ``make`` and use ``make release`` to upload to pypi.\n\nUsage\n=====\nThe libzet library provides functions to parse zettels out of Markdown\nor RST text formats and manage these zettels on the filesystem.\n\nZettel File Format\n------------------\nZettels may be stored in markdown or RST format. Each may have a title,\ncontent, and metadata in yaml format. The metadata is stored at the bottom\nbecause metadata blocks can grow quite large.\n\nHere's an example in markdown.\n\n::\n\n    # Markdown Zettel Title\n\n    Some content\n\n    ## Heading 1\n    Notes under Heading 1\n\n    <!--- attributes --->\n        ---\n        creation_date: 2023-03-09\n        zlinks: {}\n\nAnd an example in RST.\n\n::\n    \n    ==================\n     RST Zettel Title\n    ==================\n    Some content\n\n    Heading 1\n    =========\n    Notes under Heading 1\n\n    .. attributes\n    ::\n\n        ---\n        creation_date: 2023-03-09\n        zlinks: {}\n\nZettel Class\n------------\nText formatted as above may be parsed into Zettel objects.\n\n- ``zettel.title``: Title of the zettel.\n- ``zettel.headings``: Dictionary of level-2 headings within the zettel. The\n  content immediately under the title is in the ``_notes`` key.\n- ``zettel.attrs``: Attributes of the Zettel.\n\nThe ``attrs`` is a dictionary that will automatically parse date fields. Any\nkey with the word 'date' in it will be parsed. Dates read in this matter may\nbe very free-form. Plain English phrases such as \"tomorrow\" or\n\"next Wednesday\" should work fine.\n\nParsing and printing\n--------------------\nZettels can be parsed out of a string with the ``str_to_zettels`` function, and\nthen printed using the ``zettels_to_str`` function or the zettel's own\n``getMd()`` or ``getRst()`` methods.\n\n::\n\n    def str_to_zettels(text, zettel_format):\n        \"\"\" Convert a str to a list of zettels.\n    \n        This function's return may be passed to zettels_to_str.\n    \n        Args:\n            text: Text to convert to zettels.\n            zettel_format: 'rst' or 'md'.\n    \n        Returns:\n            A list of Zettel references.\n    \n        Raises:\n            ValueError if the text was invalid.\n        \"\"\"\n    \n    \n    def zettels_to_str(zettels, zettel_format, headings=None):\n        \"\"\" Return many zettels as a str.\n    \n        This function's return may be passed to str_to_zettels.\n    \n        Args:\n            zettels: List of zettels to print.\n            zettel_format: 'rst' or 'md'.\n            headings: Only print select headings.\n    \n        Returns:\n            A str representing the zettels.\n        \"\"\"\n\nFilesystem management\n---------------------\nLibzet provides functions to assist with managing zettels on the filesystem.\n\n- Create a new zettel on disk with ``create_zettel``\n- Load a list of zettels from disk with ``load_zettels``\n- Filter this list based on the needs of your application.\n- Modify the zettels and save the changes with ``save_zettels``\n- Or send them to ``edit_zettels`` to edit them in a text editor.\n- Move zettels around using ``copy_zettels`` or ``move_zettels``\n- Remove unwanted zettels with ``delete_zettels``\n\nThese functions each return valid zettel references with respect to their\nlocations on disk. The general idea for an application is to keep track\nof its zettels using the return values of these functions.\n\nA zettel's location on disk is tracked with a ``_loadpath`` attribute. These\nfunctions will automatically manage this attribute, so ensure it is not\ncarelessly modified in flight.\n\n::\n\n    def create_zettel(\n            path,\n            text='', title='', headings=None, attrs=None, zettel_format='md',\n            no_edit=False, errlog='', template=None):\n        \"\"\" Create and new zettel on disk and edit it.\n    \n        Args:\n            path: Path to create new zettel.\n            text: Provide a body of text from which to parse the whole zettel.\n            headings: Headings to create the new zettel with.\n            attrs: Default attributes to create the zettel.\n            zettel_format: 'md' or 'rst'\n            errlog: See edit_zettels\n            no_edit: Set to True to skip editing.\n            template: Optionally init the new zettel from a template. May be\n                a path to a yaml file or a dict. Defaults to ztemplate.yaml\n                within the same dir as the new zettel.\n    \n                If template exists then the headings and attrs from that\n                file will be used to init the zettel.\n    \n        Returns:\n            The new zettel reference.\n    \n        Raises:\n            FileExistsError: There was already a zettel at path.\n            ValueError: The newly created zettel was invalid.\n        \"\"\"\n    \n    \n    def load_zettels(paths, zettel_format='md', recurse=False):\n        \"\"\" Load Zettels from the filesystem.\n    \n        Zettels will be updated with a _loadpath value in their attrs.\n        Send these zettels to save_zettels after modifying them to write\n        them to disk. The _loadpath attribute will not be written to disk.\n    \n        Args:\n            paths: Path or list paths to zettels. Each may be a dir or file.\n            zettel_format: md or rst\n            recurse: True to recurse into subdirs, False otherwise.\n    \n        Returns:\n            A list of zettels.\n    \n            This list may be passed to save_zettels to write\n            them to the filesystem.\n    \n        Raises:\n            OSError if one of the files couldn't be opened.\n            ValueError if one of the zettels contained invalid text.\n        \"\"\"\n    \n    \n    def edit_zettels(zettels, zettel_format='md', headings=None, errlog='', delete=False):\n        \"\"\" Bulk edit zettels provided by load_zettels.\n    \n        Delete the text for a zettel to avoid updating it.\n    \n        It is possible to add new zettels while editing, just be sure\n        to set the _loadpath attribute for each new zettel.\n    \n        Args:\n            zettels: List of zettels to edit.\n            zettel_format: md or rst.\n            headings: Only edit specific headings for each zettel.\n            errlog: Write your working text to this location if parsing failed.\n            delete: If True, then zettels whose text is deleted during editing will\n                also be deleted from the disk.\n    \n        Returns:\n            A list of zettels that were updated. Deleted zettels will not be\n            in this list.\n    \n        Raises:\n            ValueError if any zettels were edited in an invalid way.\n        \"\"\"\n    \n    \n    def save_zettels(zettels, zettel_format='md'):\n        \"\"\" Save zettels back to disk.\n\n        the _loadpath attribute will not be written.\n    \n        Args:\n            zettels: List of zettels.\n            zettel_format: md or rst.\n    \n        Returns:\n            The list of zettels as saved to disk.\n    \n        Raises:\n            KeyError if a zettel is missing a _loadpath attribute. No zettels\n                will be written to disk if this is the case.\n    \n            OSError if a zettel's text couldn't be written to disk.\n        \"\"\"\n    \n    \n    def delete_zettels(zettels):\n        \"\"\" Delete zettels from the filesystem.\n    \n        Args:\n            zettels: Zettels to delete. Must have a _loadpath attribute.\n    \n        Returns:\n            An empty list to represent the loss of these zettels\n    \n        Raises:\n            KeyError if any zettels were missing a _loadpath. No zettels\n                will be deleted in this case.\n    \n            OSError if the zettel could not be deleted.\n        \"\"\"\n    \n    \n    def copy_zettels(zettels, dest, zettel_format='md'):\n        \"\"\" Copy zettels to a new file location.\n    \n        Zettels are saved to disk before copying.\n    \n        Args:\n            zettels: List of zettels to copy.\n            zettel_format: md or rst.\n            dest: Location to copy them to.\n    \n        Returns:\n            A list of the new zettels loaded from their new file locations.\n    \n        Raises:\n            KeyError if any zettels were missing a _loadpath. No zettels\n                will be written to disk in this case.\n    \n            OSError if any of the zettels failed to copy.\n    \n            See shutil.copy\n        \"\"\"\n    \n    \n    def move_zettels(zettels, dest, zettel_format='md'):\n        \"\"\" Move zettels. Zettels will be saved before moving.\n\n        The zettels will be deleted from their former paths which\n        invalidates their previous _loadpath. Use this function like...\n\n            zettels = move_zettels(zettels, './new-dir/')\n    \n        Args:\n            zettels: List of zettels to move.\n            zettel_format: md or rst.\n            dest: Destination directory.\n    \n        Returns:\n            A list of the zettels from their new home.\n    \n        Raises:\n            See copy_zettels and delete_zettels.\n        \"\"\"\n",
    "bugtrack_url": null,
    "license": "GPLv2",
    "summary": "Python3 library for zettel reading.",
    "version": "2.2.5",
    "project_urls": {
        "Homepage": "https://github.com/OneRedDime/libzet"
    },
    "split_keywords": [],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "a60261811f24b5684226d16125324d4f20e16cf5d6d843f09459bbd45b0a13a8",
                "md5": "d5faf780b197eeb4f44e4f2bd1535bed",
                "sha256": "94a2105030b81a368b91fec44cdaaa6f758e72a5cad98c94d802bf32b33e5cb4"
            },
            "downloads": -1,
            "filename": "libzet-2.2.5-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "d5faf780b197eeb4f44e4f2bd1535bed",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": "<4,>=3.7",
            "size": 21501,
            "upload_time": "2024-02-04T03:48:30",
            "upload_time_iso_8601": "2024-02-04T03:48:30.801414Z",
            "url": "https://files.pythonhosted.org/packages/a6/02/61811f24b5684226d16125324d4f20e16cf5d6d843f09459bbd45b0a13a8/libzet-2.2.5-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "2aa460a531d8910f149bd22e151f100979f86e90913d5cd130b173428ccb76ec",
                "md5": "6b7b4ef7ad52f4b3e2bfabc819a9e6cd",
                "sha256": "fa13455fd38a4bb7fe72b7b5b3bfd79449fe3f6a4d1e8803db1885ad5972217b"
            },
            "downloads": -1,
            "filename": "libzet-2.2.5.tar.gz",
            "has_sig": false,
            "md5_digest": "6b7b4ef7ad52f4b3e2bfabc819a9e6cd",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": "<4,>=3.7",
            "size": 23582,
            "upload_time": "2024-02-04T03:48:32",
            "upload_time_iso_8601": "2024-02-04T03:48:32.832396Z",
            "url": "https://files.pythonhosted.org/packages/2a/a4/60a531d8910f149bd22e151f100979f86e90913d5cd130b173428ccb76ec/libzet-2.2.5.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2024-02-04 03:48:32",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "OneRedDime",
    "github_project": "libzet",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": false,
    "lcname": "libzet"
}
        
Elapsed time: 0.18823s