Tutorials

The other chapters of this documentation describe what pyTooling offers, package by package. These tutorials describe how to build something with it, and each of them answers a question that the API reference cannot: not what does this class do, but which of these classes do I reach for, and in what order.

Each tutorial is self-contained. Read the one that matches the problem in front of you.

What each one is for

Structuring a program

Exception Hierarchies

Give a package one base exception and a shape below it, so a caller can catch your failures without catching everything. Start here - the decisions are cheap now and expensive later.

TUTORIAL/MetaClasses

What a meta-class is, what Python does when it creates a class, and which of the four lighter tools to reach for before reaching for a meta-class at all. Background for ExtendedType.

Decorators

The three shapes a decorator comes in - function-based with and without parameters, and class-based - and what each is good for.

Attributes

Attach declarative meta-data to classes, methods and functions, then find every entity carrying it. The alternative to a registry that every module has to remember to call.

Building and testing a program

CLI Abstraction

Wrap a command line program - git, a compiler, a simulator - as a Python class whose arguments are typed members instead of hand-assembled strings.

Terminal Application

Build a terminal program with coloured output, verbosity levels and an exit-code contract.

Unit Testing

What to test and in which order, and what the report should call it.

Application Testing

The other half: testing the program the way a user starts it, through its entry point.

A suggested order

For a new package built on pyTooling, the tutorials fall into a natural sequence. Nothing forces it - but each step makes a decision that the next one builds on:

  1. Exception Hierarchies - decide how the package reports failure, before there is code that raises. Retrofitting a base exception means touching every raise.

  2. TUTORIAL/MetaClasses - decide whether the data model needs ExtendedType, and which of its options. Slots are a class-creation decision.

  3. Unit Testing - decide the levels and the naming while the test suite is still small.

  4. CLI Abstraction or Terminal Application - the two shapes a command line tool takes: one calls other programs, the other is one.

  5. Application Testing - once there is an entry point to start.

Decorators and Attributes are reference material rather than steps; read them when a declarative annotation would be shorter than the imperative code you are about to write.