Skip to main content

Chapters utils

This module contains utils which make work with Foliant chapter lists easier.

Installation

To use functions and classes from this module, install it with command

pip3 install foliantcontrib.utils.chapters

Usage

Right now this module offers only one useful class, called Chapters. To start using it, import it:

>>> from foliant.contrib.chapters import Chapters

Let's assume we have the following list of chapters specified in foliant.yml:

chapters:
    - introduction.md
    - Overview:
        - The Problem: problem.md
        - Requirements: req.md
        - Quick Start:
            - qs/installation.md
            - qs/first_steps.md
            - qs/advanced_usage.md
    - Specifications:
        - specs/core.md
        - specs/classes.md

If we want to interact wit this list of chapters, we will probably only need path to Markdown-files in the proper order. That's exactly what the Chapters class offers. Let's translate this chapter list into Python and give it to the Chapters class:

>>> chapters_list = ['introduction.md',{'Overview': [{'The Problem': 'problem.md'},{'Requirements': 'req.md'},{'Quick Start': ['qs/installation.md','qs/first_steps.md','qs/advanced_usage.md']}]},{'Specifications': ['specs/core.md', 'specs/classes.md']}]
>>> chapters = Chapters(chapters_list)

The flat property

The flat property of the Chapters class contains the list of chapter filenames in the correct order, with all the original hierarchy neatly flattened.

>>> for chapter in chapters.flat:
...     print(chapter)
introduction.md
problem.md
req.md
qs/installation.md
qs/first_steps.md
qs/advanced_usage.md
specs/core.md
specs/classes.md

The paths method

Usually when we work with chapters, we need not just ther names, as they stated in foliant.yml, but the paths to the actual files.

This is the work of the paths method, which accepts one argument: root of the markdown-files directory (usually src or __folianttmp__).

This method returns a generator, which yields PosixPath objects to each chapter in the proper order

>>> for path in chapters.paths('src'):
...     print(repr(path))
PosixPath('src/introduction.md')
PosixPath('src/problem.md')
PosixPath('src/req.md')
PosixPath('src/qs/installation.md')
PosixPath('src/qs/first_steps.md')
PosixPath('src/qs/advanced_usage.md')
PosixPath('src/specs/core.md')
PosixPath('src/specs/classes.md')

The get_chapter_title method

Method tries to find the chapter by its path in the chapter list and returns its title, if it was defined in the chapter list.

Let's return to the example chapter list from the Usage section:

chapters:
    - introduction.md
    - Overview:
        - The Problem: problem.md
        - Requirements: req.md
        - Quick Start:
            - qs/installation.md
            - qs/first_steps.md
            - qs/advanced_usage.md
    - Specifications:
        - specs/core.md
        - specs/classes.md

In this case if we try to find the title of the req.md chapter:

>>> chapters.get_chapter_title('req.md')
'Requirements'

We get the title 'Requirements', which was defined in the config. On the other hand, if we try to get the title of a chapter qs/first_steps.md:

>>> chapters.get_chapter_title('qs/first_steps.md')
''

We will get an empty string, because the title for this chapter was not defined in the config.

Alternative usage

You can also use the Chapters object as if it was list:

>>> chapters[0]
'introduction.md'
>>> 'req.md' in chapters
True
>>> for chapter in chapters:
...     print(chapter)
...     break
introduction.md

Original chapters list is available in the chapters property:

>>> chapters.chapters
['introduction.md', {'Overview': [{'The Problem': 'problem.md'}, {'Requirements': 'req.md'}, {'Quick Start': ['qs/installation.md', 'qs/first_steps.md', 'qs/advanced_usage.md']}]}, {'Specifications': ['specs/core.md', 'specs/classes.md']}]

You can redefine your chapters on the fly:

>>> chapters.chapters = ['one.md', {'two': 'three.md'}]
>>> for chapter in chapters:
...     print(chapter)
one.md
three.md

Metadata

Release files for foliantcontrib.utils.chapters 1.0.3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for foliantcontrib.utils.chapters 1.0.3
File Size Uploaded Provenance Actions
foliantcontrib.utils.chapters-1.0.3.tar.gz 4.4 kB Without provenance Details for foliantcontrib.utils.chapters-1.0.3.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for foliantcontrib.utils.chapters 1.0.3
File Interpreter ABI Platform Actions
foliantcontrib.utils.chapters-1.0.3-py3-none-any.whl Python 3 none any Details for foliantcontrib.utils.chapters-1.0.3-py3-none-any.whl

Total release size: 9.6 kB

Release files / foliantcontrib.utils.chapters-1.0.3.tar.gz

Download URL foliantcontrib.utils.chapters-1.0.3.tar.gz
Size 4.4 kB
Tags Source
SHA-256 checksum
How to use checksums
702be01eb65fd0bb8375db5e68b2aba92ef60ba0cfc332f4807ef4888e629d1c
BLAKE2b-256 checksum
How to use checksums
ad3ffa1fbfef6159cdf60ef58ed592c4396e23a20dd536e5815202da31af7ea0
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/3.2.0 pkginfo/1.5.0.1 requests/2.24.0 setuptools/49.2.0 requests-toolbelt/0.9.1 tqdm/4.48.2 CPython/3.8.5

Release files / foliantcontrib.utils.chapters-1.0.3-py3-none-any.whl

Download URL foliantcontrib.utils.chapters-1.0.3-py3-none-any.whl
Size 5.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
c5ca7f671aafc1e4683d35147f747d22939ee6da88ed06083b8daf930918b509
BLAKE2b-256 checksum
How to use checksums
c11f97c4710cbed07f185320e7bea45e8c7242836dd691f731a2894d1c497ed5
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/3.2.0 pkginfo/1.5.0.1 requests/2.24.0 setuptools/49.2.0 requests-toolbelt/0.9.1 tqdm/4.48.2 CPython/3.8.5

Security for foliantcontrib.utils.chapters 1.0.3

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page