libjam 0.1.8__tar.gz → 0.2.0__tar.gz

libjam-0.2.0/.gitignore

@@ -0,0 +1,3 @@
+__pycache__
+dist
+docs/build

libjam-0.2.0/.readthedocs.yaml

@@ -0,0 +1,17 @@
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.14"
+  jobs:
+    install:
+      - pip install --upgrade pip
+      - pip install --group docs .
+
+sphinx:
+  configuration: docs/conf.py
+  builder: "dirhtml"

libjam-0.2.0/PKG-INFO

@@ -0,0 +1,40 @@
+Metadata-Version: 2.4
+Name: libjam
+Version: 0.2.0
+Summary: A jam of Python libraries.
+Project-URL: homepage, https://github.com/philippkosarev/libjam
+Project-URL: source, https://github.com/philippkosarev/libjam
+Project-URL: issues, https://github.com/philippkosarev/libjam/issues
+Project-URL: documentation, https://libjam.readthedocs.io
+Author-email: Philipp Kosarev <philipp.kosarev@gmail.com>
+License-Expression: GPL-2.0
+License-File: LICENSE
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.14
+Requires-Dist: filetype>=1.0.0
+Requires-Dist: platformdirs>=4.0.0
+Requires-Dist: py7zr>=1.0.0
+Requires-Dist: rarfile>=4.0
+Description-Content-Type: text/markdown
+
+# libjam
+A jam of Python libraries.
+
+## Overview
+Here is a quick overview of each module/class in libjam:
+- The [Captain](https://libjam.readthedocs.io/en/latest/captain) class provides a boilerplate-free way of creating CLIs.
+- The [Secretary](https://libjam.readthedocs.io/en/latest/secretary) class is just another program configuration system.
+- The [writer](https://libjam.readthedocs.io/en/latest/writer) module makes it easy to format and style your terminal output.
+- The [flashcard](https://libjam.readthedocs.io/en/latest/flashcard) module has a few functions for getting user input in the terminal.
+- The [drawer](https://libjam.readthedocs.io/en/latest/drawer) module provides some missing file-management pieces.
+- The [Path](https://libjam.readthedocs.io/en/latest/path) class is an extension of `pathlib`'s `Path` class, with `drawer`'s functionality.
+
+## Installation
+Releases are available on [PyPI](https://pypi.org/project/libjam) and can be installed using pip:
+```sh
+pip install libjam
+```
+
+## Documentation
+The documentation, with examples, is available [here](https://libjam.readthedocs.io).

libjam-0.2.0/README.md

@@ -0,0 +1,20 @@
+# libjam
+A jam of Python libraries.
+
+## Overview
+Here is a quick overview of each module/class in libjam:
+- The [Captain](https://libjam.readthedocs.io/en/latest/captain) class provides a boilerplate-free way of creating CLIs.
+- The [Secretary](https://libjam.readthedocs.io/en/latest/secretary) class is just another program configuration system.
+- The [writer](https://libjam.readthedocs.io/en/latest/writer) module makes it easy to format and style your terminal output.
+- The [flashcard](https://libjam.readthedocs.io/en/latest/flashcard) module has a few functions for getting user input in the terminal.
+- The [drawer](https://libjam.readthedocs.io/en/latest/drawer) module provides some missing file-management pieces.
+- The [Path](https://libjam.readthedocs.io/en/latest/path) class is an extension of `pathlib`'s `Path` class, with `drawer`'s functionality.
+
+## Installation
+Releases are available on [PyPI](https://pypi.org/project/libjam) and can be installed using pip:
+```sh
+pip install libjam
+```
+
+## Documentation
+The documentation, with examples, is available [here](https://libjam.readthedocs.io).

libjam-0.2.0/docs/captain.rst

@@ -0,0 +1,96 @@
+Captain
+=======
+
+Examples
+--------
+
+Single-command CLI
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+``example.py`` file:
+
+.. literalinclude:: singlecommand-example.py
+  :language: python
+
+Here is what the user will see when running this CLI:
+
+.. code-block::
+
+  $ ./example.py
+  shout: missing argument <TEXT>
+  Try 'shout --help' for more information.
+
+  $ ./example.py Hello
+  Hello!
+
+  $ ./example.py Hello --world
+  Hello world!
+
+  $ ./example.py --help
+  Usage:
+    shout [OPTION]... <TEXT>
+  Description:
+    Shouts the given text back.
+  Options:
+    -w, --world - Adds ' world' before the exclamation mark.
+    -h, --help  - Prints this page.
+
+
+Multi-command CLI
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+``example.py`` file:
+
+.. literalinclude:: multicommand-example.py
+  :language: python
+
+Here is what the user will see when running this CLI:
+
+.. code-block::
+
+  $ ./example.py
+  very-smart-ai: no command specified.
+  Try 'very-smart-ai --help' for more information.
+
+  $ ./example.py shout "I like crisps"
+  I like crisps!
+
+  $ ./example.py wonder -h
+  Usage:
+     very-smart-ai wonder
+  Description:
+     Where's my copy of My weekend in Stevenage by Filthy Henderson?
+  Options:
+        --mcbeth - Ponder whether to be or not to be.
+     -q --quiet   - Be quiet.
+     -h --help    - Prints this page.
+
+  $ ./example.py wonder --mcbeth
+  I just want to be a fish.
+
+  $ ./example.py --help
+  Trust me, it's the smartest one out there.
+
+  Synopsis:
+     very-smart-ai <COMMAND> ...
+
+  Commands:
+     shout   - I will be loud!
+     whisper - Shhhh! You don't want them to hear you...
+     wonder  - Where's my copy of My weekend in Stevenage by Filthy Henderson?
+
+  Usage:
+     shout <TEXT> [SUFFIX]
+     whisper [LINES]...
+     wonder
+
+  Options:
+     -h --help - Prints this page.
+
+
+API
+---
+
+.. autoclass:: libjam.Captain
+
+.. autofunction:: libjam.captain

libjam-0.2.0/docs/conf.py

@@ -0,0 +1,64 @@
+# Imports
+import os
+import sys
+import pypandoc
+
+# Project information
+project = 'libjam'
+author = 'Philipp Kosarev'
+copyright = f'2026, {author}'
+language = 'en'
+
+# Adding module to PATH
+script_dir = os.path.dirname(__file__)
+module_dir = os.path.dirname(script_dir)
+sys.path.append(module_dir)
+
+# Paths
+templates_path = ['templates']
+exclude_patterns = ['build']
+
+# Extensions
+extensions = [
+  'sphinx.ext.autodoc',
+  'sphinx_copybutton',
+  'sphinx_toolbox.more_autodoc.variables',
+]
+
+# Default autodoc options
+autodoc_default_options = {
+  'members': True,
+  'member-order': 'bysource',
+}
+
+# HTML theme options
+html_theme = 'pydata_sphinx_theme'
+html_static_path = ['static']
+html_css_files = ['style.css']
+html_sidebars = { '**': []}
+html_theme_options = {
+  'show_nav_level': 0,
+  'navigation_depth': 3,
+  'collapse_navigation': False,
+  'pygments_light_style': 'gruvbox-light',
+  'pygments_dark_style': 'zenburn',
+  'icon_links': [
+    {
+      'name': 'GitHub',
+      'url': 'https://github.com/philippkosarev/libjam',
+      'icon': 'fa-brands fa-github',
+      'type': 'fontawesome',
+    },
+  ]
+}
+
+# Hooks and directives
+def process_docstring(app, what, name, obj, options, lines):
+  """Converts markdown docstrings to ReST."""
+  md  = '\n'.join(lines)
+  rst = pypandoc.convert_text(md, 'rst', 'markdown')
+  lines[:] = rst.splitlines()
+
+# Connecting hooks
+def setup(app):
+  app.connect('autodoc-process-docstring', process_docstring)

libjam-0.2.0/docs/drawer.rst

@@ -0,0 +1,36 @@
+drawer
+======
+
+Example
+-------
+
+Here is an example CLI for extracting archives:
+
+.. code-block::
+
+  from libjam import captain, writer, drawer
+  import os
+  import sys
+
+  @captain()
+  def cli(archive, out_directory, **opts):
+    # Validating input
+    if not os.path.exists(archive):
+      cli.usage_error(f'{archive}: no such file or directory.')
+    if not os.path.isfile(archive):
+      cli.usage_error(f'{archive}: not a file.')
+    if not drawer.can_unpack(archive):
+      cli.usage_error(f'{archive}: unsupported filetype.')
+    # Extracting
+    name = os.path.basename(archive)
+    with writer.ProgressBar(f"Extracting '{name}'") as bar:
+      drawer.unpack_with_progress(archive, out_directory, bar.update)
+
+  if __name__ == '__main__':
+    sys.exit(cli())
+
+
+API
+---
+
+.. automodule:: libjam.drawer

libjam-0.2.0/docs/flashcard.rst

@@ -0,0 +1,47 @@
+flashcard
+=========
+
+Example
+-------
+
+Here is an example of an absolutely safe CLI program.
+
+``safe-program.py`` file:
+
+.. code-block::
+
+  from libjam import captain, flashcard
+  import os
+  import sys
+  import shutil
+
+  @captain()
+  def cli(**opts):
+    root = os.path.abspath(os.sep)
+    root_dirs = [os.path.join(root, f) for f in os.listdir(root)]
+    while True:
+      to_delete = flashcard.select(
+        'Which directory would you like to delete?',
+        root_dirs,
+      )
+      if not to_delete:
+        if flashcard.ask('Are you sure you want to abort?'):
+          print('Actually, I think I will delete all of them now!')
+          for f in root_dirs:
+            shutil.rmdir(f)
+          root_dirs.clear()
+      else:
+        shutil.rmdir(to_delete)
+        root_dirs.remove(to_delete)
+      if not root_dirs:
+        print('Congratulations!')
+        break
+
+  if __name__ == '__main__':
+    sys.exit(cli())
+
+
+API
+---
+
+.. automodule:: libjam.flashcard

libjam-0.2.0/docs/index.rst

@@ -0,0 +1,43 @@
+https://github.com/philippkosarev/libjam
+
+libjam
+======
+
+A jam of Python libraries.
+
+
+Overview
+--------
+
+Here is a quick overview of each module/class in libjam:
+
+- The :doc:`captain` class provides a boilerplate-free way of creating CLIs.
+- The :doc:`secretary` class is just another program configuration system.
+- The :doc:`writer` module makes it easy to format and style your terminal output.
+- The :doc:`flashcard` module has a few functions for getting user input in the terminal.
+- The :doc:`drawer` module provides some missing file-management pieces.
+- The :doc:`path` class is an extension of ``pathlib.Path`` with :doc:`drawer`'s functionality.
+
+
+Installing
+----------
+
+Releases are available on `PyPi <https://pypi.org/project/libjam/>`_ and can be installed using pip:
+
+.. code-block:: sh
+
+  pip install libjam
+
+
+Table of contents
+-----------------
+
+.. toctree::
+  :maxdepth: 2
+
+  captain
+  secretary
+  writer
+  flashcard
+  drawer
+  path

libjam-0.2.0/docs/multicommand-example.py

@@ -0,0 +1,44 @@
+#! /usr/bin/env python3
+
+# Imports
+from libjam import captain
+import sys
+
+
+# Creating the CLI
+@captain('very-smart-ai')
+class cli:
+  "Trust me, it's the smartest one out there."
+
+  def shout(text, suffix=None, *, help=False):
+    """I will be loud!"""
+    text += '!'
+    if suffix:
+      text += suffix
+    print(text)
+
+  def whisper(*lines, **opts):
+    """Shhhh! You don't want them to hear you..."""
+    lines = [l + '...' for l in lines]
+    text = '\n'.join(lines)
+    print(text)
+
+  def wonder(**opts):
+    """Where's my copy of My weekend in Stevenage by Filthy Henderson?"""
+    if opts['mcbeth']:
+      print("I just want to be a fish.")
+    elif opts['quiet']:
+      print('I REFUSE!')
+    else:
+      print('Thanks for staying quiet.')
+
+
+# Adding options to the wonder command
+cli.wonder_command.add_option(
+  'mcbeth', 'Ponder whether to be or not to be.',
+)
+cli.wonder_command.add_option('quiet', 'Be quiet.', 'q')
+
+# Running the CLI
+if __name__ == '__main__':
+  sys.exit(cli())

libjam-0.2.0/docs/path.rst

@@ -0,0 +1,35 @@
+Path
+====
+
+Example
+-------
+
+Here is an example CLI for extracting archives:
+
+.. code-block::
+
+  from libjam import captain, writer, Path
+  import sys
+
+  @captain()
+  def cli(archive, out_directory, **opts):
+    archive, out_directory = Path(archive), Path(out_directory)
+    # Validating input
+    if not archive.exists():
+      cli.usage_error(f'{archive}: no such file or directory.')
+    if not archive.is_file():
+      cli.usage_error(f'{archive}: not a file.')
+    if not archive.can_unpack():
+      cli.usage_error(f'{archive}: unsupported filetype.')
+    # Extracting
+    with writer.ProgressBar(f"Extracting '{archive.name}'") as bar:
+      archive.unpack_with_progress(out_directory, bar.update)
+
+  if __name__ == '__main__':
+    sys.exit(cli())
+
+
+API
+---
+
+.. autoclass:: libjam.Path

libjam-0.2.0/docs/secretary.rst

@@ -0,0 +1,75 @@
+Secretary
+=========
+
+Example
+-------
+
+Here is an example of how a CLI download manager might use Secretary for its configuration.
+
+``cli_config.py`` file:
+
+.. code-block::
+
+  # Imports
+  from pathlib import Path
+  from libjam import Secretary
+
+  # Defining defaults
+  default_downloads_dir = Path.home() / 'Downloads'
+  if not default_downloads_dir.is_dir():
+    default_downloads_dir = None
+  defaults = {
+    'downloads-directory': default_downloads_dir,
+  }
+
+  # Config template
+  template = '''\
+  # An override for the default downloads directory
+  # downloads-directory = ''
+  '''
+
+  # Initialising config
+  secretary = Secretary('download-manager')
+  config = secretary.file('config', defaults, template)
+
+  # Validating values
+  downloads_dir = config.get('downloads-directory')
+  if not downloads_dir:
+    config.error(
+      'Could not automatically find an existing Downloads directory.',
+      "Please specify the 'downloads-directory' manually.",
+    )
+  downloads_dir = Path(downloads_dir)
+  if not downloads_dir.is_dir():
+    config.error("The specified 'downloads-directory' does not exist.")
+
+
+``main_cli.py`` file:
+
+.. code-block::
+
+  from .cli_config import downloads_dir
+  from .download_manager import DownloadManager
+
+  download_manager = DownloadManager(downloads_dir)
+
+  # The rest of the program...
+
+
+Example error:
+
+.. code-block::
+
+  $ python -m download_manager.cli
+  Configuration error in ~/.config/download-manager/config.toml:
+  Could not automatically find an existing Downloads directory.
+  Please specify the 'downloads-directory' manually.
+
+
+API
+---
+
+.. autoclass:: libjam.Secretary
+
+.. autoclass:: libjam.File
+  :show-inheritance:

libjam-0.2.0/docs/singlecommand-example.py

@@ -0,0 +1,23 @@
+#! /usr/bin/env python3
+
+from libjam import captain
+
+# Creating the CLI
+@captain()
+def shout(text: str, *, world=False, help=False):
+  """Shouts the given text back."""
+  if world:
+    text += ' world'
+  print(text + '!')
+  return 'anything'
+
+# Adding an option to the CLI
+shout.add_option(
+  'world', "Adds ' world' before the exclamation mark.", 'w',
+)
+
+# Running the CLI
+returned = shout()
+
+# This assertion will succeed
+assert returned == 'anything'

libjam-0.2.0/docs/static/style.css

@@ -0,0 +1,26 @@
+html[data-theme="light"] {
+  --pst-color-background: hsl(30, 100%, 98.5%);
+  --pst-color-surface: hsl(27, 80%, 95.5%);
+  --pst-color-on-background: hsl(30, 100%, 96%);
+  --pst-color-text-base: hsl(10, 85%, 17%);
+  --pst-color-inline-code: hsl(23, 70%, 34%);
+  --pst-color-link-higher-contrast: hsl(25, 70%, 40%);
+  --pst-color-primary: hsl(24, 80%, 45%);
+  --pst-color-secondary: hsl(30, 100%, 50%);
+  --pst-color-accent: hsl(30, 100%, 50%);
+}
+html[data-theme="dark"] {
+  --pst-color-background: hsl(15, 1%, 10%);
+  --pst-color-text-base: hsl(45, 15%, 90%);
+  --pst-color-on-background: hsl(25, 25%, 17.5%);
+  --pst-color-surface: hsl(30, 5%, 13%);
+  --pst-color-border: hsl(30, 20%, 25%);
+  --pst-color-primary: hsl(32, 100%, 75%);
+  --pst-color-inline-code: hsl(27.5, 100%, 70%);
+  --pst-color-secondary: hsl(35, 100%, 60%);
+  --pst-color-secondary-highlight: hsl(35, 100%, 30%);
+  --pst-color-accent: hsl(35, 100%, 60%);
+  --pst-color-link-higher-contrast: hsl(35, 100%, 75%);
+  --pst-color-muted: hsl(35, 20%, 80%);
+  --pst-color-text-muted: hsl(35, 20%, 80%);
+}

libjam-0.2.0/docs/writer.rst

@@ -0,0 +1,7 @@
+writer
+======
+
+API
+---
+
+.. automodule:: libjam.writer

libjam-0.2.0/hooks/pre-commit

@@ -0,0 +1,27 @@
+#! /usr/bin/env bash
+
+# Text styles
+bold=$(tput bold)
+normal=$(tput sgr0)
+
+# Checking for potential errors
+ruff --config ruff.toml check
+status=$?
+if [[ $status == "127" ]]; then
+  echo "${bold}
+╭─Commit─Aborted──────────────────────────────────────────────╮
+│ Looks like you don't have ruff installed. This project uses │
+│ ruff to check for potential errors.                         │
+│ To install ruff you can run 'pip install ruff'.             │
+╰─────────────────────────────────────────────────────────────╯\
+${normal}"
+elif [[ $status != "0" ]]; then
+  echo "${bold}
+╭─Commit─Aborted─────────────────────────────────────────────╮
+│ Found potential errors, please fix them before committing. │
+│ To ignore the errors use '--no-verify'.                    │
+╰────────────────────────────────────────────────────────────╯\
+${normal}"
+fi
+
+exit $status

libjam-0.2.0/libjam/__init__.py

@@ -0,0 +1,13 @@
+"""A jam of Python libraries.
+
+Source code: https://github.com/philippkosarev/libjam
+Documentation: https://libjam.readthedocs.io
+PyPi page: https://pypi.org/project/libjam
+"""
+
+from .captain import Captain, captain
+from .secretary import Secretary, File
+from . import writer
+from . import flashcard
+from . import drawer
+from .path import Path