API Reference

CV generator

CV generator: convert a Markdown CV into a single-page, ATS-friendly PDF.

The input Markdown file and output PDF file are configured in a .env file in the current working directory:

MARKDOWN_FILE_URL=”cv.md” PDF_OUTPUT_LOCATION=”cv.pdf”

Experience headings may use ### Role / Company | Dates. The text before the final pipe is aligned left, while the dates are aligned right.

class scripts.cv_generator.RenderProfile(body_font_size, body_line_height, h1_font_size, spacing_scale)[source]

Bases: object

Typography and spacing values for one deterministic render attempt.

body_font_size: float

body_line_height: float

h1_font_size: float

spacing_scale: float

scripts.cv_generator.css_for_profile(profile)[source]

Return the CV stylesheet configured for a render profile.

Return type:: str

class scripts.cv_generator.ExperienceHeaderTreeprocessor(md=None)[source]

Bases: Treeprocessor

Turn level-three headings into two-column experience headers.

run(root)[source]

Split each H3 at its final pipe and add layout spans.

Return type:: Element

class scripts.cv_generator.ExperienceHeaderExtension(**kwargs)[source]

Bases: Extension

Register the CV experience-heading transformation.

extendMarkdown(md)[source]

Register the tree processor after inline Markdown is parsed.

Return type:: None

scripts.cv_generator.load_environment(env_file)[source]

Load an environment file using standard python-dotenv semantics.

Existing environment variables take precedence over values in the file.

Return type:: None

scripts.cv_generator.required_setting(name)[source]

Return a required environment setting or raise a clear error.

Return type:: str

scripts.cv_generator.local_path(value, base_directory)[source]

Resolve a local path or file URL relative to the working directory.

Return type:: Path

scripts.cv_generator.markdown_to_html(markdown_text, profile=RenderProfile(body_font_size=10.0, body_line_height=1.45, h1_font_size=19.0, spacing_scale=1.0))[source]

Convert Markdown source to a complete HTML document.

Return type:: str

scripts.cv_generator.generate_pdf(source, destination)[source]

Render one Markdown file as a single-page A4 PDF atomically.

Return type:: None

scripts.cv_generator.parse_arguments()[source]

Parse command-line arguments, providing -h/–help and rejecting others.

Return type:: None

scripts.cv_generator.main()[source]

Load configuration and generate the configured CV PDF.

Return type:: int

Website screenshots

Website screenshot: capture one 1600x900 desktop JPEG per configured site.

The site list and the output directory are configured in a .env file in the current working directory:

SCREENSHOT_SITES=”https://example.com,https://example.org” SCREENSHOT_OUTPUT_DIR=”/home/your-username/Pictures”

SCREENSHOT_SITES is a comma-separated list of http/https URLs and is required. SCREENSHOT_OUTPUT_DIR is optional and defaults to ~/Pictures; the directory is created when absent.

Each site is captured in a fresh Chromium context sized to a 1600x900 viewport at scale factor 1, and the visible viewport is written as <hostname>.jpg, overwriting the file from the previous run. GitHub Pages project sites are named after the repository instead of the shared user hostname, with underscores replaced by hyphens, so https://username.github.io/my_project/ is written as my-project.jpg.

scripts.screenshot.load_environment(env_file)[source]

Load an environment file using standard python-dotenv semantics.

Existing environment variables take precedence over values in the file.

Return type:: None

scripts.screenshot.required_setting(name)[source]

Return a required environment setting or raise a clear error.

Return type:: str

scripts.screenshot.default_output_directory()[source]

Return the screenshot directory used when none is configured.

Return type:: Path

scripts.screenshot.parse_sites(value)[source]

Return the validated website URLs listed in a comma-separated value.

Return type:: list[str]

scripts.screenshot.load_config()[source]

Return the configured sites and the prepared output directory.

Return type:: tuple[list[str], Path]

scripts.screenshot.hostname_to_filename(url)[source]

Return the .jpg filename for a website URL.

The hostname names the file, except on GitHub Pages project sites, where every project shares one <username>.github.io hostname; those are named after the first path segment (the repository) instead, with underscores replaced by hyphens.

Return type:: str

Args:: url: The website URL to derive a filename from.
Returns:: The filename to write the screenshot to.
Raises:: ValueError: If the URL carries no hostname.

scripts.screenshot.hide_cookie_banners(page)[source]

Remove known cookie-banner elements, ignoring selectors that fail.

Return type:: None

scripts.screenshot.capture_website(browser, url, output_directory)[source]

Capture one website as a 1600x900 JPEG in the output directory.

Return type:: None

scripts.screenshot.parse_arguments()[source]

Parse command-line arguments, providing -h/–help and rejecting others.

Return type:: None

scripts.screenshot.main()[source]

Capture every configured website and report the per-site outcome.

Return type:: int

Media library organizer

Build a verified, copy-only photo and video library from an approved plan.

The command has three phases: scan reads metadata without changing source files, plan writes SQLite and Markdown manifests, and apply copies and verifies the files described by an approved SQLite manifest. report writes a SQLite inventory of the media in a directory, such as a finished library. duplicates saves groups of files with identical decoded visual content to a SQLite report without changing them. review-duplicates serves a temporary page on the loopback interface for comparing those copies and is the only command that deletes source media: one confirmed copy at a time, after revalidating it against the report.

class scripts.media_organizer.MediaMetadata(path, original_filename, extension, original_directory, file_size, mtime_ns, media_type='video', duration=None, width=None, height=None, rotation=0, recording_timestamp=None, recording_timezone=None, timestamp_provenance=None, latitude=None, longitude=None, detailed_place=None, title=None, camera=None, country=None, locality=None, location_provenance=None, warnings=<factory>)[source]

Bases: object

Metadata and provenance collected for one candidate media file.

path: str

original_filename: str

extension: str

original_directory: str

file_size: int

mtime_ns: int

media_type: str = 'video'

duration: Optional[float] = None

width: Optional[int] = None

height: Optional[int] = None

rotation: int = 0

recording_timestamp: Optional[str] = None

recording_timezone: Optional[str] = None

timestamp_provenance: Optional[str] = None

latitude: Optional[float] = None

longitude: Optional[float] = None

detailed_place: Optional[str] = None

title: Optional[str] = None

camera: Optional[str] = None

country: Optional[str] = None

locality: Optional[str] = None

location_provenance: Optional[str] = None

warnings: list[str]

class scripts.media_organizer.Location(country, locality, detailed_place=None)[source]

Bases: object

A country and parent locality returned by a geographic resolver.

country: str

locality: str

detailed_place: Optional[str] = None

class scripts.media_organizer.Geocoder(*args, **kwargs)[source]

Bases: Protocol

Interface used to resolve coordinates without coupling to a provider.

resolve(latitude, longitude)[source]

Return a reliable parent locality for coordinates, if available.

Return type:: Optional[Location]

class scripts.media_organizer.NullGeocoder[source]

Bases: object

Default resolver that never transmits coordinates.

resolve(latitude, longitude)[source]

Leave GPS coordinates unclassified.

Return type:: Optional[Location]

class scripts.media_organizer.NominatimGeocoder(index, url='https://nominatim.openstreetmap.org/reverse')[source]

Bases: object

Opt-in OpenStreetMap Nominatim resolver with SQLite-backed caching.

resolve(latitude, longitude)[source]

Resolve coordinates, preferring city, town, or village fields.

Return type:: Optional[Location]

class scripts.media_organizer.MetadataIndex(path)[source]

Bases: object

Persistent metadata and reverse-geocoding cache.

close()[source]

Close the SQLite connection.

Return type:: None

get(path)[source]

Return cached metadata when the file identity matches a current record.

Return type:: Optional[MediaMetadata]

put(metadata)[source]

Insert or replace cached metadata for a source file.

Return type:: None

get_geocode(latitude, longitude)[source]

Return an exactly cached coordinate lookup.

Return type:: Optional[Location]

put_geocode(latitude, longitude, location)[source]

Cache an exact coordinate lookup without radius-based merging.

Return type:: None

scripts.media_organizer.default_index_path()[source]

Return a cache path outside a typical source media directory.

Return type:: Path

scripts.media_organizer.discover_media(source, excluded=())[source]

Return supported media candidates below source in deterministic order.

Return type:: list[Path]

scripts.media_organizer.extract_metadata(path)[source]

Validate media with FFprobe and combine FFprobe/ExifTool metadata.

Return type:: MediaMetadata

scripts.media_organizer.load_overrides(path)[source]

Load optional classifications and recognizable place aliases from JSON.

Return type:: dict[str, Any]

scripts.media_organizer.classify_location(metadata, source, geocoder, overrides)[source]

Classify a media file using the documented conservative priority order.

Return type:: None

scripts.media_organizer.scan_library(source, index, geocoder, overrides, excluded=(), progress=None)[source]

Discover media, reuse valid cache records, and classify each file.

Return type:: tuple[list[MediaMetadata], list[dict[str, str]]]

scripts.media_organizer.sanitize_component(value, fallback='Unclassified')[source]

Return an ASCII alphanumeric component with hyphen separators.

Return type:: str

scripts.media_organizer.source_folder_title(source)[source]

Return a filename-safe title derived from the source folder name.

Return type:: str

scripts.media_organizer.english_country_name(value)[source]

Return a known English country name, preserving unknown source text.

Return type:: str

scripts.media_organizer.english_locality_name(value)[source]

Return a known English locality name, preserving unknown source text.

Return type:: str

scripts.media_organizer.sha256_file(path, progress=None)[source]

Return a streaming SHA-256 digest for a file.

Return type:: str

scripts.media_organizer.validate_separate_trees(source, output)[source]

Reject identical, nested, or enclosing source/output directory trees.

Return type:: tuple[Path, Path]

scripts.media_organizer.build_plan(source, output, media_files, skipped, progress=None)[source]

Build a deterministic, hash-bound organization manifest.

Return type:: dict[str, Any]

scripts.media_organizer.write_plan(plan, database_path, markdown_path)[source]

Atomically write a SQLite plan and its human-readable Markdown report.

Return type:: None

scripts.media_organizer.load_plan(path)[source]

Load and minimally validate a versioned organization plan.

Return type:: dict[str, Any]

scripts.media_organizer.apply_plan(plan_path, progress=None)[source]

Copy, hash-verify, and finalize every safe entry in an approved plan.

Return type:: tuple[int, int, int]

scripts.media_organizer.display_size(metadata)[source]

Return the width and height as displayed, after any quarter-turn rotation.

Return type:: Optional[tuple[int, int]]

scripts.media_organizer.orientation_label(size)[source]

Name the orientation of a displayed width and height.

Return type:: str

scripts.media_organizer.organized_location(path)[source]

Return the country and locality recorded by an organized copy’s path.

Return type:: Optional[Location]

scripts.media_organizer.build_report(directory, media_files, skipped)[source]

Count the media types, formats, orientations, and locations in a directory.

Return type:: dict[str, Any]

scripts.media_organizer.write_report(report, path)[source]

Atomically store a media inventory in a normalized SQLite database.

Return type:: None

scripts.media_organizer.load_report(path)[source]

Load a media inventory from its normalized SQLite database.

Return type:: dict[str, Any]

scripts.media_organizer.find_duplicates(source, progress=None)[source]

Group the media below source whose decoded visual content is identical.

Only files of equal size are decoded and compared. Each (device, inode) pair counts once, so a hard link or symlink never forms a group with the file it names, and a candidate resolving outside source is skipped. Source files are only read.

Return type:: dict[str, Any]

scripts.media_organizer.visual_digest(metadata)[source]

Return a SHA-256 digest of the decoded visual content of a media file.

FFmpeg decodes every visual stream of a photo, or the first visual stream of a video, to rgba64le frames without applying rotation. The digest covers the displayed size, the rotation, each stream’s #dimensions and #sar lines, and each frame’s stream index, byte size, and hash in order, but not timestamps or the #software and #tb lines.

Return type:: str

scripts.media_organizer.write_duplicate_report(report, path)[source]

Atomically store duplicate groups in a normalized SQLite database.

Return type:: None

scripts.media_organizer.load_duplicate_report(path)[source]

Load a duplicate report after validating its schema and relations.

Return type:: dict[str, Any]

scripts.media_organizer.serve_duplicate_review(report_path, port=8765)[source]

Serve the review page for a duplicate report until interrupted.

The system browser opens the tokenized page once the loopback port is bound. Requests are handled one at a time, and the server and the report database are closed when serving ends, including after Ctrl+C.

Return type:: None

class scripts.media_organizer.DuplicateReviewServer(report_path, port=8765)[source]

Bases: HTTPServer

Serve one duplicate report on the loopback interface, one request at a time.

property url: str: Return the tokenized address of the review page.

server_close()[source]

Close the listening socket and the report database.

Return type:: None

class scripts.media_organizer.DuplicateReviewHandler(request, client_address, server)[source]

Bases: BaseHTTPRequestHandler

Answer token-protected requests for the review page and its previews.

server: DuplicateReviewServer

log_message(format, *args)[source]

Keep request lines, which carry the access token, off the console.

Return type:: None

end_headers()[source]

Add the security headers to every response before ending them.

Return type:: None

do_GET()[source]

Serve the review page or one entry’s preview to a token holder.

Return type:: None

do_POST()[source]

Delete one confirmed copy, then redirect back to the review page.

A report that cannot be read or updated gets a fixed 500 response.

Return type:: None

do_PUT()