API Reference

Friendly tour of the public modules you can import when you want to script Super Pocket instead of clicking around the CLI.

Core & CLI

Super Pocket - A collection of developer tools.

This package provides various utilities for developers including: - Markdown rendering and conversion - Project-to-file exporters - PDF conversion tools - Web utilities (favicon generation, job search, etc.)

Pocket - Unified CLI entry point.

This module provides a unified command-line interface for all Pocket functionalities, organized into logical subcommands.

super_pocket.cli.main()[source]: Main entry point for the CLI.

super_pocket.interactive.pocket_cmd()[source]

super_pocket.interactive.project_cmd()[source]

super_pocket.interactive.documents_cmd()[source]

super_pocket.interactive.pdf_cmd()[source]

super_pocket.interactive.web_cmd()[source]

super_pocket.interactive.readme_cmd()[source]

super_pocket.interactive.xml_cmd()[source]

Markdown

Markdown rendering and conversion tools.

super_pocket.markdown.render_markdown(content, console=None)[source]

Render Markdown content to the terminal using Rich.

Parameters:

content (str) – The Markdown content to render.
console (Console | None) – Optional Console instance. If not provided, a new one is created.

Raises:

errors.MarkdownError – If there’s an error rendering the markdown.

super_pocket.markdown.read_markdown_file(file_path)[source]

Read the contents of a Markdown file.

Parameters:

file_path (Path) – Path to the Markdown file to read.

Returns:

The file contents as a string.

Raises:

FileNotFoundError – If the file does not exist.
ValueError – If the path is not a file.
PermissionError – If the file cannot be read.
IOError – If there’s an error reading the file.

Return type:

str

Markdown renderer using Rich library.

This module provides functionality to read and render Markdown files beautifully in the terminal using the Rich library for enhanced formatting and syntax highlighting.

Combines functionality from both fancy_md.py and markd.py.

super_pocket.markdown.renderer.read_markdown_file(file_path)[source]

Read the contents of a Markdown file.

Parameters:

file_path (Path) – Path to the Markdown file to read.

Returns:

The file contents as a string.

Raises:

FileNotFoundError – If the file does not exist.
ValueError – If the path is not a file.
PermissionError – If the file cannot be read.
IOError – If there’s an error reading the file.

Return type:

str

super_pocket.markdown.renderer.render_markdown(content, console=None)[source]

Render Markdown content to the terminal using Rich.

Parameters:

content (str) – The Markdown content to render.
console (Console | None) – Optional Console instance. If not provided, a new one is created.

Raises:

errors.MarkdownError – If there’s an error rendering the markdown.

Projects

Project management and export tools.

super_pocket.project.create_codebase_markdown(project_path, output_file, exclude_str)[source]

Scan a project and generate a comprehensive Markdown documentation file.

This function walks through a project directory, generates a file tree visualization, and includes the content of all text-based files in a single Markdown document with proper syntax highlighting. Perfect for documentation, code reviews, or feeding entire codebases to AI tools.

The generated Markdown file includes: 1. Project title (based on directory name) 2. ASCII tree structure of the project 3. Content of each file with syntax highlighting

Parameters:

project_path (str) – Path to the project root directory.
output_file (str) – Path to the output Markdown file. If None, defaults to ‘<project_name>-1-file.md’.
exclude_str (str) – Comma-separated string of files/directories to exclude (e.g., “node_modules,.git,__pycache__”).

Raises:

IOError – If there’s an error writing to the output file.
SystemExit – If the project path doesn’t exist or an error occurs during processing.

Example

>>> create_codebase_markdown(
...     project_path='/path/to/my-app',
...     output_file='my-app.md',
...     exclude_str='node_modules,.git,dist'
... )
|| Starting project scan: 'my-app'
...
|| Success! Codebase compiled into 'my-app.md'

Project to file converter.

This module scans a project directory and generates a single Markdown file containing the entire codebase with syntax highlighting and file tree structure.

super_pocket.project.to_file.get_language_identifier(filename)[source]

Determine the language identifier for a Markdown code block based on file extension.

This function maps file extensions to their corresponding language identifiers for proper syntax highlighting in Markdown code blocks. Special files like ‘Dockerfile’ are handled separately.

Parameters:

filename (str) – The name of the file (can be basename or full path).

Returns:

Language identifier for syntax highlighting (e.g., ‘python’, ‘javascript’).: Returns ‘plaintext’ if the extension is not recognized.

Return type:

str

Example

>>> get_language_identifier('script.py')
'python'
>>> get_language_identifier('Dockerfile')
'dockerfile'

super_pocket.project.to_file.generate_tree(root_dir, exclude)[source]

Generate a text representation of the project tree structure.

Creates an ASCII tree visualization of the directory structure, similar to the Unix ‘tree’ command. Excludes specified files and directories from the output. Uses box-drawing characters (│, ├, └) for visual hierarchy.

Parameters:

root_dir (str) – Root directory to scan.
exclude (Set[str]) – Set of file/directory names to exclude from the tree.

Yields:

str – Lines representing the tree structure with proper indentation.

Example

>>> for line in generate_tree('/path/to/project', {'node_modules', '.git'}):
...     print(line)
├── src/
│   ├── main.py
│   └── utils.py

super_pocket.project.to_file.create_codebase_markdown(project_path, output_file, exclude_str)[source]

Scan a project and generate a comprehensive Markdown documentation file.

This function walks through a project directory, generates a file tree visualization, and includes the content of all text-based files in a single Markdown document with proper syntax highlighting. Perfect for documentation, code reviews, or feeding entire codebases to AI tools.

The generated Markdown file includes: 1. Project title (based on directory name) 2. ASCII tree structure of the project 3. Content of each file with syntax highlighting

Parameters:

project_path (str) – Path to the project root directory.
output_file (str) – Path to the output Markdown file. If None, defaults to ‘<project_name>-1-file.md’.
exclude_str (str) – Comma-separated string of files/directories to exclude (e.g., “node_modules,.git,__pycache__”).

Raises:

IOError – If there’s an error writing to the output file.
SystemExit – If the project path doesn’t exist or an error occurs during processing.

Example

>>> create_codebase_markdown(
...     project_path='/path/to/my-app',
...     output_file='my-app.md',
...     exclude_str='node_modules,.git,dist'
... )
|| Starting project scan: 'my-app'
...
|| Success! Codebase compiled into 'my-app.md'

class super_pocket.project.req_to_date.PackageInput(*, package, version)[source]

Bases: BaseModel

package: str

version: str

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class super_pocket.project.req_to_date.PackageResult(*, package, current_version, latest_patch=None, latest_overall=None, status, message=None)[source]

Bases: BaseModel

package: str

current_version: str

latest_patch: str | None

latest_overall: str | None

status: str

message: str | None

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class super_pocket.project.req_to_date.CheckRequest(*, packages)[source]

Bases: BaseModel

packages: List[PackageInput]

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

super_pocket.project.req_to_date.parse_package_specs(specs)[source]

Convert the CLI arguments list to PackageInput objects.

super_pocket.project.req_to_date.parse_version(version_str)[source]

Parse a version in semver format

super_pocket.project.req_to_date.find_latest_patch(current_version, all_versions)[source]

Find the latest patch compatible version

async super_pocket.project.req_to_date.check_package(pkg, version)[source]

Check a package on PyPI

async super_pocket.project.req_to_date.root()[source]

async super_pocket.project.req_to_date.check_packages(request)[source]

Check a list of packages and return the available updates

async super_pocket.project.req_to_date.check_packages_from_specs(specs)[source]

Utility interface for the command line.

super_pocket.project.req_to_date.run_req_to_date(packages)[source]

Synchronous entry point for CLI (standalone or via pocket).

super_pocket.project.req_to_date.print_req_to_date_results(results, printer)[source]

Shared helper to render results for both CLIs.

The caller provides a small printer callback so that each CLI can control its own styling/output mechanism.

CLI commands for project initialization.

Provides Click commands for listing, showing, and initializing projects from templates.

super_pocket.project.init.cli.list_templates(templates_dir)[source]

List all available templates.

Parameters:: templates_dir (Path) – Directory containing template manifests
Returns:: List of template info dicts
Return type:: list[dict]

README Generator

README generator for Super Pocket.

Main project detector that orchestrates all analyzers.

class super_pocket.readme.detector.ProjectDetector[source]

Bases: object

Detect project language and type using multiple analyzers.

__init__()[source]: Initialize detector with all available analyzers.

detect(project_path)[source]

Detect project context by trying all analyzers.

Parameters:: project_path (Path) – Path to the project directory
Returns:: ProjectContext if detected, None otherwise
Return type:: ProjectContext | None

Main README generator.

class super_pocket.readme.generator.ReadmeGenerator[source]

Bases: object

Generate README files from project context.

__init__()[source]: Initialize generator with section templates.

generate(context, selected_badges, selected_sections)[source]

Generate README content.

Parameters:

context (ProjectContext) – Project context
selected_badges (List[BadgeType]) – List of badge types to include
selected_sections (List[str]) – List of optional section IDs to include

Returns:

Complete README markdown content

Return type:

str

CLI commands for README generator.

PDF

Note

Requires super-pocket[pdf] optional dependencies.

PDF conversion tools.

super_pocket.pdf.convert_to_pdf(input_file, output_file)[source]

Convert a .txt or .md file to PDF.

Parameters:

input_file (Path) – Path to the input file (.txt or .md).
output_file (Path) – Path to the output PDF file.

Raises:

ValueError – If file extension is not supported.
FileNotFoundError – If input file doesn’t exist.

super_pocket.pdf.convert_txt_to_pdf(input_file, output_file)[source]

Convert a text file to PDF using fpdf2.

Creates a simple PDF with Arial font at 12pt size. Each line from the text file is rendered as a multi-cell paragraph in the PDF.

Parameters:

input_file (Path) – Path to the input text file.
output_file (Path) – Path to the output PDF file.

Raises:

ImportError – If fpdf2 library is not installed.

super_pocket.pdf.convert_md_to_pdf(input_file, output_file)[source]

Convert a Markdown file to PDF using markdown-pdf.

Preserves Markdown formatting including headers, lists, code blocks, and other Markdown elements in the generated PDF document.

Parameters:

input_file (Path) – Path to the input Markdown file.
output_file (Path) – Path to the output PDF file.

Raises:

ImportError – If markdown-pdf library is not installed.

PDF conversion tools.

This module provides functionality to convert text and Markdown files to PDF format.

super_pocket.pdf.converter.convert_to_pdf(input_file, output_file)[source]

Convert a .txt or .md file to PDF.

Parameters:

input_file (Path) – Path to the input file (.txt or .md).
output_file (Path) – Path to the output PDF file.

Raises:

ValueError – If file extension is not supported.
FileNotFoundError – If input file doesn’t exist.

super_pocket.pdf.converter.convert_txt_to_pdf(input_file, output_file)[source]

Convert a text file to PDF using fpdf2.

Creates a simple PDF with Arial font at 12pt size. Each line from the text file is rendered as a multi-cell paragraph in the PDF.

Parameters:

input_file (Path) – Path to the input text file.
output_file (Path) – Path to the output PDF file.

Raises:

ImportError – If fpdf2 library is not installed.

super_pocket.pdf.converter.convert_md_to_pdf(input_file, output_file)[source]

Convert a Markdown file to PDF using markdown-pdf.

Preserves Markdown formatting including headers, lists, code blocks, and other Markdown elements in the generated PDF document.

Parameters:

input_file (Path) – Path to the input Markdown file.
output_file (Path) – Path to the output PDF file.

Raises:

ImportError – If markdown-pdf library is not installed.

super_pocket.pdf.converter.main()[source]: Main entry point for standalone script.

Web

Note

Requires super-pocket[web] optional dependencies.

Web utilities (favicon generation, etc.).

super_pocket.web.convert_to_favicon(input_file, output_file='favicon.ico', sizes=[(256, 256), (128, 128), (64, 64), (48, 48), (32, 32), (16, 16)])[source]

Convert an image to a favicon (.ico) file with multiple sizes.

Parameters:

input_file (str) – Path to the input image file.
output_file (str) – Path to the output .ico file.
sizes (List[Tuple[int, int]] | None) – List of (width, height) tuples for icon sizes. Defaults to standard favicon sizes.

Raises:

FileNotFoundError – If input file doesn’t exist.
ImportError – If PIL/Pillow is not installed.
ValueError – If output file doesn’t have .ico extension.

Favicon generation tools.

This module provides functionality to convert images to favicon (.ico) format with multiple sizes for web compatibility.

super_pocket.web.favicon.convert_to_favicon(input_file, output_file='favicon.ico', sizes=[(256, 256), (128, 128), (64, 64), (48, 48), (32, 32), (16, 16)])[source]

Convert an image to a favicon (.ico) file with multiple sizes.

Parameters:

input_file (str) – Path to the input image file.
output_file (str) – Path to the output .ico file.
sizes (List[Tuple[int, int]] | None) – List of (width, height) tuples for icon sizes. Defaults to standard favicon sizes.

Raises:

FileNotFoundError – If input file doesn’t exist.
ImportError – If PIL/Pillow is not installed.
ValueError – If output file doesn’t have .ico extension.

super_pocket.web.favicon.main()[source]: Main entry point for standalone script.

Job search module using the JSearch API.

This module provides functionality to search for job postings using the RapidAPI JSearch API. It allows filtering results by country, language, employment type, requirements, and other criteria. Results can be exported to JSON format.

super_pocket.web.job_search.get_jobs(query, page=1, num_pages=10, country='fr', language='fr', date_posted='month', employment_types='FULLTIME', job_requirements='no_experience', work_from_home=False)[source]

Retrieves job postings via the JSearch API.

Makes a request to the RapidAPI JSearch API to search for job postings based on the specified criteria.

Parameters:

query (str) – The search term for job postings.
page (int) – The page number to start from. Default: 1.
num_pages (int) – The number of pages to retrieve. Default: 10.
country (str) – The country code for the search (e.g., “fr”, “us”). Default: “fr”.
language (str) – The language code for results (e.g., “fr”, “en”). Default: “fr”.
date_posted (str) – The posting period (“today”, “week”, “month”, “all”). Default: “month”.
employment_types (str) – The type of employment sought (“FULLTIME”, “PARTTIME”, “CONTRACTOR”, “INTERN”). Default: “FULLTIME”.
job_requirements (str) – Experience requirements (“under_3_years_experience”, “more_than_3_years_experience”, “no_experience”, “no_degree”). Default: “no_experience”.
work_from_home (bool) – If True, filters only remote work jobs. Default: False.

Returns:

The JSON response data containing job postings.

Return type:

dict

Raises:

requests.exceptions.RequestException – If an error occurs during the HTTP request.

super_pocket.web.job_search.save_jobs_to_json(jobs, filename)[source]

Saves job postings to a JSON file.

Writes job posting data to a JSON file formatted with 4-space indentation for better readability.

Parameters:

jobs (dict) – The dictionary containing job posting data.
filename (str) – The path to the output JSON file.

Raises:

IOError – If an error occurs while writing the file.

Templates & Cheatsheets

Templates and cheatsheets management module.

Provides CLI commands to: - List available templates and cheatsheets - View/display content in terminal - Copy templates to user projects - Validate template syntax

CLI for managing templates and cheatsheets.

Provides commands to: - List available templates and cheatsheets - View/display content in terminal - Copy templates to user projects - Validate template syntax

super_pocket.documents.cli.get_available_items(item_type)[source]

Get list of available templates or cheatsheets.

Scans the appropriate directory and returns all Markdown files (.md) found, sorted alphabetically by filename.

Parameters:: item_type (Literal['templates', 'cheatsheets']) – Either “templates” or “cheatsheets” to specify which directory to scan.
Returns:: Sorted list of Path objects for available Markdown items.
Return type:: list[Path]

Example

>>> templates = get_available_items("templates")
>>> [t.name for t in templates]
['agent_template.md', 'unit_tests_agent.md']

Template validator module.

Provides functionality to validate the syntax and structure of agent configuration templates.

exception super_pocket.documents.validator.TemplateValidationError[source]

Bases: Exception

Exception raised when template validation fails.

super_pocket.documents.validator.validate_markdown_syntax(content)[source]

Validate basic Markdown syntax.

Parameters:: content (str) – Markdown content to validate.
Returns:: List of warning/error messages (empty if valid).
Return type:: List[str]

super_pocket.documents.validator.validate_agent_template(file_path)[source]

Validate an agent configuration template.

Parameters:

file_path (Path) – Path to the template file.

Returns:

‘valid’: bool
’issues’: list of issues found
’warnings’: list of warnings

Return type:

Dictionary with validation results

super_pocket.documents.validator.validate_template_file(file_path, verbose=True)[source]

Validate a template file and optionally print results.

Parameters:

file_path (Path) – Path to the template file.
verbose (bool) – If True, print validation results.

Returns:

True if valid, False otherwise.

Return type:

bool

XML Helper

super_pocket.xml.xml.extract_text(file)[source]

super_pocket.xml.xml.parse_custom_syntax(text)[source]: Parse recursively a string in the format ‘tag:<content>’ to transform it into XML.

super_pocket.xml.xml.format_xml(xml_string)[source]: Format a raw XML string with correct indentation.

Utilities

super_pocket.settings.add_help_command(group)[source]

Add a ‘help’ subcommand to a Click group.

This allows users to get help via ‘pocket <group> help’ in addition to ‘pocket <group> –help’ and ‘pocket <group> -h’.

Parameters:: group – A Click group to add the help command to.
Returns:: The group with the help command added.

super_pocket.settings.add_help_argument(command)[source]

Make a command support ‘help’ as a positional argument.

For commands, this allows users to type ‘pocket <cmd> help’ to get help, in addition to ‘-h’ and ‘–help’.

Parameters:: command – A Click command to modify.
Returns:: The modified command.

super_pocket.settings.centered_spinner(message='Loading...', style='bold blue')[source]

super_pocket.settings.display_logo()[source]

super_pocket.utils.print_error(error, custom=False, message=None)[source]

Programmatic Examples

Render Markdown

from pathlib import Path
from src.super_pocket.markdown.renderer import read_markdown_file, render_markdown

content = read_markdown_file(Path("README.md"))
render_markdown(content)  # prints to the terminal via Rich

Export a project to one file

from src.super_pocket.project.to_file import create_codebase_markdown

create_codebase_markdown(
    project_path=".",
    output_file="export.md",
    exclude_str=".git,venv,node_modules"
)

Audit dependencies

from src.super_pocket.project.req_to_date import run_req_to_date

results = run_req_to_date(("requests==2.31.0", "rich>=13"))
for pkg in results:
    print(pkg.package, pkg.current_version, "->", pkg.latest_overall)

Generate a README programmatically

from pathlib import Path
from src.super_pocket.readme.detector import ProjectDetector
from src.super_pocket.readme.generator import ReadmeGenerator

context = ProjectDetector().detect(Path("."))
content = ReadmeGenerator().generate(context, selected_badges=[], selected_sections=[])
Path("README.md").write_text(content)

Convert to PDF

from pathlib import Path
from src.super_pocket.pdf.converter import convert_to_pdf

convert_to_pdf(Path("README.md"), Path("README.pdf"))

Make a favicon

from pathlib import Path
from src.super_pocket.web.favicon import convert_to_favicon

convert_to_favicon(
    input_file=Path("logo.png"),
    output_file=Path("favicon.ico"),
    sizes="64x64,32x32,16x16"
)

Build XML for LLMs

from src.super_pocket.xml.xml import parse_custom_syntax, format_xml

raw = parse_custom_syntax("note:hello world")
pretty = format_xml(raw)
print(pretty)

Error handling is standard Python exceptions (FileNotFoundError, ValueError, etc.). Most modules avoid fancy wrappers so you can catch and log as you like.

API Stability

Public functions/classes documented here are the intended surface area. Private helpers (prefixed with _) can change without notice. Super Pocket follows semantic versioning for releases.