Topazdocs
Start Here

Learning path

Choose a browser or local starting point, then follow a single study-plan application from its initial run to a tested two-module Python product.

Outcome: Select the appropriate starting environment and follow the step-by-step progression from a single .tpz file to a tested two-module product.

Prerequisites: You only need a text editor and basic familiarity with the terminal. The final lesson requires Python 3.11 or newer.

Choose your starting point

Use the Playground to modify and run short code snippets without installing local dependencies. It covers the first four lessons, but it cannot generate the package or artifact built in the final lesson.

Install Topaz locally to complete the entire learning path. First Program provides installation options for standard shells, PowerShell, and npm, followed by consistent topaz CLI commands across all platforms.

Most readers complete the five hands-on lessons in about an hour. You can pause at any readiness check and resume later. Each lesson leaves the study-plan application in a working state.

If you already program in another language, start with Coming From Other Languages. It shows what transfers unchanged and what does not, so you can take only the lessons you need.

What you will build

The application evolves incrementally across lessons:

  1. First Program — Write a study-plan value, run check and run, and resolve a static type diagnostic.
  2. Values and Functions — Add explicit and inferred types, introduce a function, and manage the single mutable variable required by the application.
  3. Data and Control — Model study tasks using nominal data types, store them in a collection, and control execution using if, match, and for.
  4. Failures and Resources — Process invalid input using Option, Result, and ?, ensure cleanup with defer, and inspect an intentional error condition.
  5. First Application — Modularize the codebase into src/main.tpz and src/plan.tpz, add a test suite, lock and verify package dependencies, and build a Python product.

The final command executes the generated artifact from a directory containing no .tpz files, operating independently of the Topaz project structure and compiler. Topics such as package registries, browser lifecycle management, HTTP hosting, and backend architecture are optional next steps rather than initial prerequisites.

Decision: Playground or local tools?

Choose the Playground to evaluate expressions quickly in the browser. Choose a local installation to build the tested application and retain its output artifact. You can begin in the browser and transition to a local environment before the final lesson without losing context.

Try this

Decide where you will complete the course. Do you require a local installation now?

Answer

Use the Playground for an initial syntax overview. Install Topaz locally before the First Application lesson, as it generates source files, executes test suites, and builds a Python distribution package. If you plan to complete the entire guide in one session, starting locally avoids switching tools midway.

Ready to continue when

You have selected your starting environment, understand that the target output is a tested two-module Python product, and have either opened the Playground or prepared your environment for installing topaz.

Continue to First Program. Keep Syntax at a Glance open as a quick reference whenever you need to review language constructs.