Skip to content

README.md

Latest commit

 

History

History
193 lines (149 loc) · 6.79 KB

README.md

File metadata and controls

193 lines (149 loc) · 6.79 KB
Raw

Python Reference

A structured library of beginner-friendly Python reference cards with a small command-line browser, reusable Markdown templates and generated metadata.

The project currently contains 53 completed reference cards across seven topic categories. It is a working and growing part of the wider Engineering Knowledge Base, with the long-term goal of supplying content to a Flutter application.

Features

  • Browse cards through structured topic menus.
  • Search all available cards directly by name.
  • Open the selected Markdown card in its associated Windows application.
  • Keep every card organised with YAML front matter.
  • Export card metadata and content to a reusable JSON index.
  • Create consistent new cards from the included templates.

Available Topics

Topic Cards Examples
Built-in functions 14 len, range, enumerate
Data types 8 list, dict, tuple
Dictionary methods 1 get
List functions and methods 10 append, pop, sorted
Modules 2 functools, reduce
Set methods 2 add, union
String methods 16 split, strip, replace
Total 53

Project Structure

Python-reference/
|-- app/
|   |-- python_cheat_sheet.py   # Structured CLI card browser
|   |-- md_paths.py             # Paths used by the browser
|   |-- greetings_function.py   # Search-prompt greetings
|   `-- save_metadata.py        # YAML-to-JSON metadata exporter
|-- docs/                       # Markdown cards grouped by topic
|-- metadata/
|   `-- python_metadata.json    # Generated card index
|-- templates/                  # Templates for creating new cards
|-- todolist.md                 # Development roadmap
`-- README.md

Requirements

You must have Python 3 installed on your computer to run the reference browser. The browser itself uses only Python's standard library, so no extra Python packages are required.

Open PowerShell or Command Prompt and check that Python is available:

python --version

If the command displays a Python 3 version, you are ready to continue. If Windows reports that python is not recognised, install Python from python.org and enable the option to add Python to PATH during installation. On Windows, you can also try the Python launcher with py --version and use py instead of python in the commands below.

Run the Reference Browser from the Command Line

Open PowerShell or Command Prompt and change directory to the root of the Engineering Knowledge Base repository. For example:

cd C:\path\to\Engineering-Knowledge-Base

Then start the program:

python .\Python-reference\app\python_cheat_sheet.py

If your terminal is already inside the Python-reference folder, run:

python .\app\python_cheat_sheet.py

If your Windows installation uses the py launcher, the equivalent command is:

py .\Python-reference\app\python_cheat_sheet.py

Use q from the main menu to close the program.

The main menu displays the available categories:

+----------------------------------------------------------+
|                 PYTHON REFERENCE BROWSER                 |
+----------------------------------------------------------+
|  53 reference cards available                            |
|                                                          |
|  1  Built-in functions                                   |
|  2  Data types                                           |
|  3  List functions and methods                           |
|  4  String methods                                       |
|  5  Dictionary methods                                   |
|  6  Set methods                                          |
|  7  Modules                                              |
|                                                          |
|  s  Search all cards                                     |
|  q  Quit                                                 |
+----------------------------------------------------------+

Choose a numbered topic to see all cards available in that category. Type a listed name, such as append, to open its Markdown card. The category menu remains active so that another card can be opened afterwards.

Controls

Input Action
1 to 7 Open a topic menu
Card name Open the corresponding Markdown card
b Return to the main menu
s Search across every category
help Show topics while using global search
q Quit from the main menu

Note

The browser uses os.startfile() to open Markdown files, so the current CLI is intended for Windows.

Configure a Markdown Reader on Windows

The reference cards are Markdown (.md) files. To read them with the CLI, you need a Markdown reader or editor installed on your computer. The project does not require a specific application; you can use whichever Markdown reader you prefer.

The CLI asks Windows to open the selected card with the default application associated with .md files. Configure that application before using the browser:

  1. Install the Markdown reader or editor you want to use.
  2. Find any .md file in File Explorer.
  3. Right-click the file and select Open with.
  4. Select Choose another app.
  5. Choose your preferred Markdown reader. If it is not shown, select More apps or Choose an app on your PC and locate it manually.
  6. Enable Always use this app to open .md files.
  7. Select OK.

After this setup, choosing a card in the Python Reference Browser will open it automatically in that Markdown reader. To change readers later, repeat the same steps and choose a different application.

Reference-Card Format

Each reference card starts with YAML front matter describing information such as its title, category, difficulty and related topics. This data is intended to support future search, filtering and cross-reference features.

When creating a card:

  1. Start with the appropriate file in templates/.
  2. Save the new Markdown file in the correct folder below docs/.
  3. Add its path to app/md_paths.py and the appropriate browser dictionary.
  4. Rebuild the metadata index.

Rebuild the Metadata Index

The CLI browser uses only the Python standard library. The metadata exporter additionally requires PyYAML:

python -m pip install PyYAML
python Python-reference/app/save_metadata.py

The exporter scans the cards in a stable order and writes the generated index to metadata/python_metadata.json.

Project Status

This Python reference is an active learning project, not a finished Python documentation replacement. Planned cards and future application features are tracked in the todolist.md development roadmap.