eptr2-convenience-wrappers

name

eptr2-convenience-wrappers

description

Use typed get_* convenience wrapper functions from eptr2.calls instead of eptr.call("key", ...). These wrappers provide type hints, bilingual (EN/TR) docstrings, auto-complete, and an optional eptr argument. Use when writing scripts with typed functions, generating wrapper-based code, asking which get_* function to use, or preferring IDE-friendly code. Triggers on: get_mcp, get_smp, get_rt_cons, get_rt_gen, convenience wrapper, typed function, eptr2.calls, get_ function, wrapper call.

eptr2 Convenience Wrappers (eptr2.calls)

Overview

Every endpoint exposed by EPTR2.call is available as a typed get_* function in eptr2.calls. These wrappers give you:

• Type hints on every parameter (str, str | int, list, bool).
• Bilingual docstrings (EN/TR) with category and EPIAS reference URL.
• Auto-complete in IDEs.
• Optional eptr argument — omit it for one-off calls; pass an instance for TGT-recycling / batch usage.

There are 233 wrappers in total (231 endpoint keys + 2 aliases: ptf, smf), distributed across 21 per-category modules (see module layout below for the full list). The per-module counts shown in section headers below are for reference; use python -c "import eptr2.calls as c; print(len(c.__all__))" to confirm the total at any time.

---

Signature shape

def get_<endpoint>(
    <required_param>: <type>,
    ...,
    <optional_param>: <type> | None = None,
    ...,
    eptr: EPTR2 | None = None,
    **kwargs,
):
    """<EN title> / <TR title>

    Category: <GÖP / GİP / DGP / …>

    EN (<EN title>):
        <English description>

    TR (<TR title>):
        <Turkish description>

    Reference: <EPIAS URL>
    """

Extra **kwargs are forwarded to EPTR2.call (e.g. postprocess=False).

---

Basic usage

Date parameters accept 'YYYY-MM-DD' strings (interpreted in Europe/Istanbul timezone). Datetime parameters such as date_time accept 'YYYY-MM-DDTHH:MM:SS'.

Return type: by default every get_* function returns a pandas DataFrame. Pass postprocess=False to receive the raw JSON (list of dicts) instead.

from eptr2 import EPTR2
from eptr2.calls import get_mcp, get_smp, get_rt_cons, get_rt_gen

eptr = EPTR2(use_dotenv=True, recycle_tgt=True)

# Prices
mcp  = get_mcp(start_date="2024-07-29", end_date="2024-07-29", eptr=eptr)
smp  = get_smp(start_date="2024-07-29", end_date="2024-07-29", eptr=eptr)

# Consumption / generation
cons = get_rt_cons(start_date="2024-07-29", end_date="2024-07-29", eptr=eptr)
gen  = get_rt_gen(start_date="2024-07-29", end_date="2024-07-29", eptr=eptr)

Lazy client (no explicit eptr)

from eptr2.calls import get_ptf

# EPTR2() is constructed automatically, reading credentials from .env
df = get_ptf(start_date="2024-07-29", end_date="2024-07-29")

---

Module layout and key wrappers

Wrappers are grouped into per-category modules.

Prices – eptr2.calls.dam (18 wrappers)

Function	Required params	Key endpoint
get_mcp / get_ptf	start_date, end_date	Market Clearing Price (GÖP)
get_smp / get_smf	start_date, end_date	System Marginal Price
get_mcp_smp_imb	start_date, end_date	Positive/negative imbalance prices
get_interim_mcp	start_date, end_date	Interim (pre-final) MCP
get_dam_clearing	start_date, end_date	DAM clearing results; optional org_id
get_dam_volume	start_date, end_date	DAM trade value
get_supply_demand	date_time	Supply-demand curve at a point in time

from eptr2.calls import get_mcp, get_mcp_smp_imb, get_dam_clearing

mcp = get_mcp(start_date="2024-07-01", end_date="2024-07-31")
imb = get_mcp_smp_imb(start_date="2024-07-01", end_date="2024-07-31")
clr = get_dam_clearing(start_date="2024-07-01", end_date="2024-07-31", org_id=123)

Balancing Power Market – eptr2.calls.bpm (5 wrappers)

Function	Required params
get_bpm_up	start_date, end_date
get_bpm_down	start_date, end_date
get_smp (also here)	start_date, end_date
get_smp_dir	start_date, end_date
get_smf (alias for smp)	start_date, end_date

from eptr2.calls import get_bpm_up, get_bpm_down
up   = get_bpm_up(start_date="2024-07-01", end_date="2024-07-31")
down = get_bpm_down(start_date="2024-07-01", end_date="2024-07-31")

Consumption – eptr2.calls.consumption (24 wrappers)

Function	Required params
get_rt_cons	start_date, end_date
get_uecm	start_date, end_date
get_load_plan	start_date, end_date
get_consumption_by_province	start_date, end_date

from eptr2.calls import get_rt_cons, get_uecm, get_load_plan

cons     = get_rt_cons(start_date="2024-07-01", end_date="2024-07-31")
uecm     = get_uecm(start_date="2024-07-01", end_date="2024-07-31")
forecast = get_load_plan(start_date="2024-07-01", end_date="2024-07-31")

Generation – eptr2.calls.generation (16 wrappers)

Function	Required params	Optional
get_rt_gen	start_date, end_date	pp_id
get_uevm	start_date, end_date	pp_id
get_dpp	start_date, end_date	org_id

from eptr2.calls import get_rt_gen, get_uevm, get_dpp

all_gen   = get_rt_gen(start_date="2024-07-01", end_date="2024-07-31")
plant_gen = get_rt_gen(start_date="2024-07-01", end_date="2024-07-31", pp_id=1234)
uevm      = get_uevm(start_date="2024-07-01", end_date="2024-07-31")
dpp       = get_dpp(start_date="2024-07-01", end_date="2024-07-31", org_id=456)

Intraday Market – eptr2.calls.idm (8 wrappers)

Function	Required params
get_idm_wap	start_date, end_date
get_idm_volume	start_date, end_date
get_idm_summary	start_date, end_date

from eptr2.calls import get_idm_wap, get_idm_volume

wap    = get_idm_wap(start_date="2024-07-01", end_date="2024-07-31")
volume = get_idm_volume(start_date="2024-07-01", end_date="2024-07-31")

Imbalance – eptr2.calls.imbalance (4 wrappers)

Function	Required params
get_imbalance_volume	start_date, end_date
get_imbalance_amount	start_date, end_date

from eptr2.calls import get_imbalance_volume, get_imbalance_amount

vol = get_imbalance_volume(start_date="2024-07-01", end_date="2024-07-31")
amt = get_imbalance_amount(start_date="2024-07-01", end_date="2024-07-31")

Renewables – eptr2.calls.renewables (12 wrappers)

from eptr2.calls import get_yek_g_amount, get_res_capacity

yek = get_yek_g_amount(start_date="2024-07-01", end_date="2024-07-31")

Bilateral Contracts – eptr2.calls.bilateral (3 wrappers)

from eptr2.calls import get_bilateral_contracts
contracts = get_bilateral_contracts(start_date="2024-07-01", end_date="2024-07-31")

Transmission – eptr2.calls.transmission (14 wrappers)

# All identifiers use ASCII-only names (no Turkish characters).
from eptr2.calls import get_capacity_demand, get_congestion_cost, get_line_capacities
cap = get_capacity_demand(start_date="2024-07-01", end_date="2024-07-31")

Dams – eptr2.calls.dams (10 wrappers)

from eptr2.calls import get_reservoir_level, get_dam_active_fullness

Ancillary Services – eptr2.calls.ancillary (4 wrappers)

from eptr2.calls import get_pfk_main, get_sfk_main

Natural Gas Markets

21 modules total; the 6 modules not shown in sections above: general (8), mms (5), reporting (7), retroactive (8), vep (12), yek_g (10), plus the 4 natural-gas modules below.

(11 sections × listed counts) + general(8) + mms(5) + reporting(7) + retroactive(8) + vep(12) + yek_g(10) + ng(65) = 233.

• eptr2.calls.ng_general (2), ng_sgp (27), ng_transmission (15), ng_vgp (21)

from eptr2.calls.ng_vgp import get_ng_vgp_matching_quantity

---

Discovering what's available

import eptr2.calls as calls

# All public wrapper names
print(len(calls.__all__))   # 233

# Inspect a specific wrapper (signature + bilingual docstring)
help(calls.get_mcp)
help(calls.get_dam_clearing)

# List all wrappers whose name contains a keyword
print([n for n in calls.__all__ if "cons" in n])

---

When to use get_* vs eptr.call

Situation	Use
IDE / type-checked code	get_*
One-off quick script	get_*
Dynamic endpoint (endpoint key in a variable)	eptr.call
Iterating over all endpoint keys	eptr.call
Both approaches call the same underlying API	—

---

Forwarding extra kwargs

By default get_* functions return a pandas DataFrame. Pass postprocess=False to receive the raw JSON (list of dicts).

Anything accepted by EPTR2.call can be forwarded:

# Return raw JSON instead of DataFrame
raw = get_mcp(
    start_date="2024-07-29",
    end_date="2024-07-29",
    postprocess=False,
)

# Custom request timeout
df = get_rt_gen(
    start_date="2024-07-29",
    end_date="2024-07-29",
    request_kwargs={"timeout": 30},
)

---

Regenerating wrappers

After adding/changing endpoints in mapping/path.py or mapping/parameters.py:

python scripts/generate_call_wrappers.py

This rebuilds all 21 per-category modules under src/eptr2/calls/.

---

Reference

• Source: src/eptr2/calls/
• Generator: scripts/generate_call_wrappers.py
• Help metadata: eptr2.mapping.help.get_help_d
• User guide: docs/user-guide/convenience-wrappers.md
• API reference: docs/api/calls.md