Python Quick Peek

Contents

• Getting Started
• Importing Trade Dangerous
• Creating a TradeORM
• Looking Things Up
• Disambiguation
• Exploring Objects
• Running a command from Python
• Other Useful Parts of TD
• Want To Go Further

Getting Started

Trade Dangerous is primarily an application, but it can also be imported from Python.

This page is a quick peek for people who want to poke around, write small helpers, or understand how the command layer talks to the database. It is not a frozen public API reference; for serious development, read the source and the developer docs in the repository.

Importing Trade Dangerous

Use the package import:

import tradedangerous as td

Common imports:

from tradedangerous import TradeEnv, TradeORM
from tradedangerous.version import __version__

Check the version:

print(__version__)

Creating a TradeORM

The current database-facing interface is TradeORM.

from tradedangerous import TradeEnv, TradeORM

tdenv = TradeEnv()
tdb = TradeORM(tdenv=tdenv)

try:
    print(tdb.tradingStationCount)
finally:
    tdb.close(final=True)

TradeORM opens the configured Trade Dangerous database and provides the resolver/query interface used by the command layer. It does not preload the galaxy into an old-style in-memory database object.

Looking Things Up

A lot of useful TD work starts with lookups.

Systems

sol = tdb.lookup_system("sol")
print(sol.name)
print(sol.pos_x, sol.pos_y, sol.pos_z)

Stations

abe = tdb.lookup_station("sol/abraham lincoln")
print(abe.dbname())
print(abe.system.name)

Flexible place lookup

lookup_place() can return either a System or a Station.

place = tdb.lookup_place("sol")
print(type(place), place.name)

place = tdb.lookup_place("@sol")
print(type(place), place.name)

place = tdb.lookup_place("sol/abraham lincoln")
print(type(place), place.dbname())

Items, categories, and ships

gold = tdb.lookup_item("gold")
metals = tdb.lookup_category("metals")
asp = tdb.lookup_ship("asp")

Disambiguation

The resolver uses the same naming syntax as the CLI.

Force a system match with @

sol = tdb.lookup_place("@sol")

Force a station match with /

abe = tdb.lookup_place("/abraham lincoln")

Match a station within a system

abe = tdb.lookup_place("sol/abraham lincoln")

Duplicate system names

When more than one real system shares a name, TD reports candidates with indexed names such as:

Some System@1
Some System@2

Use the indexed form to choose the one you want.

The important thing to remember is that @ is doing two related but different jobs:

• @name means "this is definitely a system name"
• name@2 means "pick the second matching system with this name"

Exploring Objects

Once you have looked something up, Python gives you a couple of good ways to inspect it.

type(sol)
help(sol)
dir(sol)

You can also inspect useful attributes directly:

print(sol.name, sol.pos_x, sol.pos_y, sol.pos_z)
print(abe.name, abe.ls_from_star, abe.max_pad_size)
print(abe.system.name)

The objects you get back are SQLAlchemy ORM objects from tradedangerous.db.orm_models.

Running a command from Python

The command layer parses argv through CommandIndex, then runs the command against a backend selected from the command's declared needs.

Minimal example:

from tradedangerous.commands import CommandIndex
from tradedangerous import TradeORM

argv = ["trade", "market", "sol/abraham lincoln"]
cmdenv = CommandIndex().parse(argv)
tdb = TradeORM(tdenv=cmdenv, require_db=True)

try:
    results = cmdenv.run(tdb)
    if results:
        results.render()
finally:
    tdb.close(final=True)

For normal user workflows, prefer running trade ... directly. Programmatic command execution is mainly useful for tools that intentionally embed TD.

Other Useful Parts of TD

TradeEnv

TradeEnv carries environment/config/debug/detail settings.

TradeORM

TradeORM is the current database and resolver interface.

Planner modules

The route planner lives under tradedangerous.planner. The command layer converts CLI input into a RunRequest; the planner returns a RunResult; renderers turn that result into CLI/GUI output.

Exceptions

Most TD-specific exceptions live under tradedangerous.tradeexcept or the command-layer exception modules.

Want To Go Further

Read the developer docs in the repository:

• docs/Developers/RESOLVER_CONTRACT.md
• docs/Developers/ORM_Schema_reference.md
• docs/Developers/db_engine_reference.md
• docs/Developers/planner-internals.md

And when in doubt, check the current source. It is the real reference for internals.