Configuring PyneCore

PyneCore provides a simple yet powerful configuration system that is primarily based on TOML files. This guide will help you understand the key configuration components and how to use them effectively.

Working Directory Structure

The working directory is where PyneCore stores data, configuration files, output files, and scripts. A typical PyneCore working directory looks like this:

workdir/
├── .pyne             # Workdir marker (workdir_version)
├── config/           # api.toml, plugins/<plugin>.toml, optional brokers.toml / symbol_map.toml
├── data/             # Data files (.ohlcv files and their .toml companions)
├── scripts/          # Your Pyne code (.py files and their .toml companions)
│   └── lib/          # Your libraries
├── output/           # Plot, strategy statistics and trade CSVs; logs/
└── cache/            # Runtime state written by PyneCore (e.g. auth sessions)

PyneCore automatically discovers the working directory by:

  1. Using the current directory if it contains a .pyne marker file; otherwise a workdir subfolder of it
  2. Repeating the same check up the parent directories (10 levels including the current one)
  3. If nothing is found, using ./workdir (the CLI asks before creating it)

Configuration Files

PyneCore’s main TOML configuration files are:

  1. Symbol configuration files - Located alongside the .ohlcv data files
  2. Script configuration files - Located alongside your Pyne code

The config/ directory of the workdir holds the rest:

  • api.toml: PyneSys API key and timeout, used by PyneComp
  • plugins/<plugin>.toml: Settings of each installed plugin, generated automatically
  • brokers.toml: Cross-broker defaults for live trading, created on first use
  • symbol_map.toml: Optional symbol map (see below)

Symbol Configuration

Each OHLCV data file has a corresponding TOML file with the same name (but .toml extension) that contains information about the symbol. This information is used by:

  • The PyneCore runtime system to handle timeframe and session calculations
  • Your scripts via the syminfo module to access symbol properties

Example of a symbol configuration file (capitalcom_EURUSD_15.toml):

[symbol]
prefix = "CAPITALCOM"
description = "EUR/USD"
ticker = "EURUSD"
currency = "USD"
basecurrency = "EUR"
period = "15"
type = "forex"
mintick = 0.00001000
pricescale = 100000
minmove = 1.00000000
pointvalue = 1
timezone = "US/Eastern"
volumetype = "base"
avg_spread = 0.00007430

# Opening hours
[[opening_hours]]
day = 0
start = "00:00:00"
end = "16:59:50"

# Many more opening hours entries...

# Session starts
[[session_starts]]
day = 0
time = "17:05:00"

# More session entries...

The symbol configuration is initially created by the data provider when you download data, or by the converter when you import CSV/JSON/TXT data, but you can modify it if needed. This is particularly useful when you need to:

  • Adjust session times to match TradingView’s behavior for backtesting consistency
  • Fix timezone information for a particular exchange
  • Set the correct point value or tick size for a symbol
  • Verify basecurrency is the bare base asset code ("BTC", not "BTCUSDT" or "BTC.P") — PyneCore relies on this for crypto qty rounding precision (see syminfo.basecurrency)

Always review the generated TOML before running a script against it. The data downloader and CSV converter do their best to populate every field from the source data, but the symbol-info derivation is heuristic — exchange metadata is incomplete, fragmented, or absent for many tickers. Open the .toml and confirm that every value your script will read (syminfo.mintick, pointvalue, currency, basecurrency, timezone, session windows, etc.) is correct for the instrument; a silently-wrong field can drift backtest results away from TradingView without any visible error.

Script Configuration

Each script (indicator or strategy) can have a corresponding TOML file that controls its settings and input parameters. This file is automatically generated when you run an indicator or strategy (unless PYNE_SAVE_SCRIPT_TOML=0), and you can modify it to change settings without editing the script.

Example of a script configuration file (barupdown.toml):

# Indicator / Strategy / Library Settings

[script]
#overlay = false
#behind_chart = true
# Many more script settings...

# Input Settings

[inputs.maxIdLossPcnt]
# Input metadata, cannot be modified
# input_type: "float"
#     defval: 1
#      title: "Max Intraday Loss(%)"
#    confirm: false
# Change here to modify the input value
#value =

The script configuration file has two main sections:

  1. Script settings ([script]) - Control how your script executes. Settings you have not changed are written commented out; uncomment a line to override it:

    • For indicators: overlay, format, max_lines_count, etc.
    • For strategies: initial_capital, commission_value, slippage, etc.

  2. Input settings ([inputs.XXX]) - Control the input values for your script:

    • Each input declared as a main() parameter default (input.*() functions) gets its own section
    • The metadata is displayed as comments and cannot be modified
    • You can set the value to override the default value

Symbol Map (optional)

A third, optional config file — config/symbol_map.toml — translates the TradingView-canonical symbols your script references into the provider-native symbols your data files carry, so request.security() contexts resolve without an explicit --security mapping:

[symbol_map]
"NASDAQ:AAPL"   = "capitalcom:AAPL"
"BINANCE:BTCUSDT" = "ccxt:BYBIT:BTC/USDT:USDT"

See Symbol Map for the full schema, precedence rules, and backtest-vs-live behavior.

How Configuration is Used

Symbol Configuration Usage

The symbol configuration is used in several ways:

  1. By the runtime system to determine:

    • When a bar is the first bar of a session
    • How to handle timeframes
    • Converting between ticks, points, and price

  2. By your scripts via the syminfo module:

    from pynecore.lib import syminfo, session

def main():
    # Access symbol configuration
    print(f"Trading {syminfo.ticker} on {syminfo.prefix}")
    print(f"Minimum tick: {syminfo.mintick}")

    # Check if we're in a session
    if session.ismarket:
        # Do something during market hours
        pass

Script Configuration Usage

The script configuration is used to:

  1. Control script behavior through the @script.indicator or @script.strategy decorator:

    @script.indicator(
    title="My Indicator",
    overlay=True,
    format=lib.format.price,
    precision=2
)
def main():
    # These settings can be overridden in the TOML file
    pass

  2. Provide input values through input.*() functions used as main() parameter defaults:

    from pynecore.lib import script, input, close

@script.indicator("My Indicator")
def main(
    length: int = input.int(14, title="MA Length"),   # overridable in the TOML file
    source: float = input.source(close, title="Source"),
):
    ...

The script loads its configuration from the TOML file (if it exists) when it starts running. Any changes to the TOML file will take effect the next time you run the script.

Modifying Configuration Files

When modifying symbol configuration files, be careful to maintain the correct format, especially for:

  • Opening hours (which define when the market is open)
  • Session starts and ends (which define when a new trading session begins)
  • Technical parameters like mintick and pointvalue (which affect price calculations)

When modifying script configuration files:

  • Only change the value = lines under input sections
  • Only uncomment and change script settings that you need to modify
  • The script will save its configuration with updated values when it runs

Environment Variables

PyneCore also recognizes a few environment variables:

  • PYNE_WORK_DIR: Working directory path (same as the --workdir CLI option)
  • PYNE_DATA_DIR: Use this directory for OHLCV data instead of workdir/data
  • PYNESYS_API_KEY: PyneSys API key for PyneComp (overrides config/api.toml)
  • PYNE_NO_LOGO: If set, suppresses the PyneCore logo at startup
  • PYNE_QUIET: Suppresses the PyneCore logo (same as PYNE_NO_LOGO)
  • PYNE_SAVE_SCRIPT_TOML: Set to “0” to disable saving script TOML files (default: “1”)