acevo-sdk 0.1.0__tar.gz

acevo_sdk-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SimLaps
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

acevo_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,193 @@
+Metadata-Version: 2.4
+Name: acevo-sdk
+Version: 0.1.0
+Summary: Python SDK for Assetto Corsa Evo log parsing and shared-memory telemetry.
+Author-email: Gleb Zverinskiy <gleb.zverinskiy@gmail.com>
+Maintainer-email: Gleb Zverinskiy <gleb.zverinskiy@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/glebulon/acevo-sdk
+Project-URL: Issues, https://github.com/glebulon/acevo-sdk/issues
+Project-URL: Source, https://github.com/glebulon/acevo-sdk
+Keywords: assetto-corsa-evo,ace,acevo,sim-racing,telemetry,racing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Games/Entertainment :: Simulation
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: build>=1.2.0; extra == "dev"
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
+Requires-Dist: ruff>=0.6.0; extra == "dev"
+Requires-Dist: twine>=5.0.0; extra == "dev"
+Dynamic: license-file
+
+# acevo-sdk
+
+`acevo-sdk` is a Python SDK for Assetto Corsa Evo log parsing and shared-memory telemetry.
+
+It packages the reusable telemetry foundation extracted from SimLaps so other projects can build on ACE data without reimplementing log parsing, binary decoding, or shared-memory capture.
+
+This is an independent community SDK. It is not official Kunos Simulazioni or Assetto Corsa software.
+
+## Install
+
+```bash
+pip install acevo-sdk
+```
+
+For local development from this repository:
+
+```bash
+python -m pip install -e ".[dev]"
+```
+
+## What It Includes
+
+- ACE log parsing for sessions, laps, sectors, validity, player identity, car, track, tyre compound, setup notes, and fuel signals.
+- Live shared-memory capture for ACE physics, graphics, and static regions on Windows.
+- Decoders for captured shared-memory bytes.
+- Reusable dataclasses for laps, sessions, stints, frames, capture metadata, and shared session state.
+- Track catalog helpers and bundled track catalog data.
+
+## What It Does Not Include
+
+- SimLaps API submission.
+- Discord notifications.
+- Personal-best cache.
+- Desktop UI.
+- Signing, anti-cheat, or server security helpers.
+- HTML telemetry reports, AI prompts, or the larger telemetry analyzer pipeline.
+
+Those belong in downstream applications for now.
+
+## Use Cases
+
+- Build lap-tracking apps like SimLaps that parse ACE logs, detect sessions, laps, sectors, validity, and send structured data to a custom backend.
+- Capture live shared-memory telemetry for dashboards, overlays, stream widgets, engineering tools, or race-control utilities.
+- Decode saved raw shared-memory dumps offline for reverse engineering, debugging, analysis notebooks, or regression tests.
+- Build coaching tools that consume lap, sector, car, track, fuel, tyre, and telemetry signals, while keeping AI/report generation in the downstream app.
+- Create personal data pipelines that export ACE session data to JSONL, SQLite, DuckDB, Parquet, spreadsheets, or analytics services.
+- Build test fixtures and validation tools for ACE telemetry integrations without each project reimplementing log parsing and binary decoding.
+- Prototype future setup/tuning tools on top of stable decoded telemetry and catalog APIs.
+
+## Parse Logs
+
+```python
+import asyncio
+from acevo import LogParser
+
+
+async def main():
+    parser = LogParser()
+    sessions = await parser.parse_file()
+    for session in sessions:
+        print(session.track, session.car, session.best_lap)
+
+
+asyncio.run(main())
+```
+
+You can pass a specific log file or directory:
+
+```python
+parser = LogParser(r"C:\Users\you\Saved Games\ACE\Logs")
+```
+
+## Capture Shared Memory
+
+Live shared-memory capture is Windows-only because ACE exposes telemetry through Win32 file mappings.
+
+```python
+import asyncio
+from acevo import TelemetryCapture
+
+
+async def main():
+    capture = TelemetryCapture(hz=20)
+    await capture.start_capture()
+    await asyncio.sleep(30)
+    frames = await capture.stop_capture()
+    print(f"captured {len(frames)} frames")
+
+
+asyncio.run(main())
+```
+
+If your application already knows whether the game is running, you can inject a callback:
+
+```python
+capture = TelemetryCapture(game_running_callback=lambda: True)
+```
+
+When no callback is provided, the SDK does not enforce game-process detection.
+
+## Decode Raw Bytes
+
+```python
+from pathlib import Path
+from acevo import decode_graphics, decode_static
+
+graphics_bytes = bytes.fromhex(Path("graphics_frame.hex").read_text().strip())
+static_bytes = bytes.fromhex(Path("static_frame.hex").read_text().strip())
+
+graphics = decode_graphics(graphics_bytes)
+static = decode_static(static_bytes)
+
+print(graphics)
+print(static)
+```
+
+## Public API
+
+```python
+from acevo import (
+    LogParser,
+    TelemetryCapture,
+    RegionReader,
+    FrameData,
+    CaptureMetadata,
+    decode_physics,
+    decode_graphics,
+    decode_static,
+    LapData,
+    SessionData,
+    LapState,
+    SharedSessionManager,
+)
+```
+
+## Status
+
+`acevo-sdk` is Alpha software. Version `0.1.0` is the first extracted SDK release, so public APIs may change while real downstream use cases settle.
+
+Please report issues at https://github.com/glebulon/acevo-sdk/issues.
+
+## Publishing
+
+This repo is designed for PyPI Trusted Publishing through GitHub Actions.
+
+Release checklist:
+
+```bash
+python -m pip install -e ".[dev]"
+ruff check .
+pytest
+python -m build
+git tag v0.1.0
+git push origin v0.1.0
+```
+
+Create the GitHub Release for `v0.1.0`; the publish workflow uploads the package to PyPI.
+
+## License
+
+MIT

acevo_sdk-0.1.0/README.md

@@ -0,0 +1,161 @@
+# acevo-sdk
+
+`acevo-sdk` is a Python SDK for Assetto Corsa Evo log parsing and shared-memory telemetry.
+
+It packages the reusable telemetry foundation extracted from SimLaps so other projects can build on ACE data without reimplementing log parsing, binary decoding, or shared-memory capture.
+
+This is an independent community SDK. It is not official Kunos Simulazioni or Assetto Corsa software.
+
+## Install
+
+```bash
+pip install acevo-sdk
+```
+
+For local development from this repository:
+
+```bash
+python -m pip install -e ".[dev]"
+```
+
+## What It Includes
+
+- ACE log parsing for sessions, laps, sectors, validity, player identity, car, track, tyre compound, setup notes, and fuel signals.
+- Live shared-memory capture for ACE physics, graphics, and static regions on Windows.
+- Decoders for captured shared-memory bytes.
+- Reusable dataclasses for laps, sessions, stints, frames, capture metadata, and shared session state.
+- Track catalog helpers and bundled track catalog data.
+
+## What It Does Not Include
+
+- SimLaps API submission.
+- Discord notifications.
+- Personal-best cache.
+- Desktop UI.
+- Signing, anti-cheat, or server security helpers.
+- HTML telemetry reports, AI prompts, or the larger telemetry analyzer pipeline.
+
+Those belong in downstream applications for now.
+
+## Use Cases
+
+- Build lap-tracking apps like SimLaps that parse ACE logs, detect sessions, laps, sectors, validity, and send structured data to a custom backend.
+- Capture live shared-memory telemetry for dashboards, overlays, stream widgets, engineering tools, or race-control utilities.
+- Decode saved raw shared-memory dumps offline for reverse engineering, debugging, analysis notebooks, or regression tests.
+- Build coaching tools that consume lap, sector, car, track, fuel, tyre, and telemetry signals, while keeping AI/report generation in the downstream app.
+- Create personal data pipelines that export ACE session data to JSONL, SQLite, DuckDB, Parquet, spreadsheets, or analytics services.
+- Build test fixtures and validation tools for ACE telemetry integrations without each project reimplementing log parsing and binary decoding.
+- Prototype future setup/tuning tools on top of stable decoded telemetry and catalog APIs.
+
+## Parse Logs
+
+```python
+import asyncio
+from acevo import LogParser
+
+
+async def main():
+    parser = LogParser()
+    sessions = await parser.parse_file()
+    for session in sessions:
+        print(session.track, session.car, session.best_lap)
+
+
+asyncio.run(main())
+```
+
+You can pass a specific log file or directory:
+
+```python
+parser = LogParser(r"C:\Users\you\Saved Games\ACE\Logs")
+```
+
+## Capture Shared Memory
+
+Live shared-memory capture is Windows-only because ACE exposes telemetry through Win32 file mappings.
+
+```python
+import asyncio
+from acevo import TelemetryCapture
+
+
+async def main():
+    capture = TelemetryCapture(hz=20)
+    await capture.start_capture()
+    await asyncio.sleep(30)
+    frames = await capture.stop_capture()
+    print(f"captured {len(frames)} frames")
+
+
+asyncio.run(main())
+```
+
+If your application already knows whether the game is running, you can inject a callback:
+
+```python
+capture = TelemetryCapture(game_running_callback=lambda: True)
+```
+
+When no callback is provided, the SDK does not enforce game-process detection.
+
+## Decode Raw Bytes
+
+```python
+from pathlib import Path
+from acevo import decode_graphics, decode_static
+
+graphics_bytes = bytes.fromhex(Path("graphics_frame.hex").read_text().strip())
+static_bytes = bytes.fromhex(Path("static_frame.hex").read_text().strip())
+
+graphics = decode_graphics(graphics_bytes)
+static = decode_static(static_bytes)
+
+print(graphics)
+print(static)
+```
+
+## Public API
+
+```python
+from acevo import (
+    LogParser,
+    TelemetryCapture,
+    RegionReader,
+    FrameData,
+    CaptureMetadata,
+    decode_physics,
+    decode_graphics,
+    decode_static,
+    LapData,
+    SessionData,
+    LapState,
+    SharedSessionManager,
+)
+```
+
+## Status
+
+`acevo-sdk` is Alpha software. Version `0.1.0` is the first extracted SDK release, so public APIs may change while real downstream use cases settle.
+
+Please report issues at https://github.com/glebulon/acevo-sdk/issues.
+
+## Publishing
+
+This repo is designed for PyPI Trusted Publishing through GitHub Actions.
+
+Release checklist:
+
+```bash
+python -m pip install -e ".[dev]"
+ruff check .
+pytest
+python -m build
+git tag v0.1.0
+git push origin v0.1.0
+```
+
+Create the GitHub Release for `v0.1.0`; the publish workflow uploads the package to PyPI.
+
+## License
+
+MIT

acevo_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,67 @@
+[build-system]
+requires = ["setuptools>=77.0.3", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "acevo-sdk"
+version = "0.1.0"
+description = "Python SDK for Assetto Corsa Evo log parsing and shared-memory telemetry."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Gleb Zverinskiy", email = "gleb.zverinskiy@gmail.com" }]
+maintainers = [{ name = "Gleb Zverinskiy", email = "gleb.zverinskiy@gmail.com" }]
+keywords = [
+    "assetto-corsa-evo",
+    "ace",
+    "acevo",
+    "sim-racing",
+    "telemetry",
+    "racing",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Operating System :: Microsoft :: Windows",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Games/Entertainment :: Simulation",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = []
+
+[project.optional-dependencies]
+dev = [
+    "build>=1.2.0",
+    "pytest>=8.0.0",
+    "pytest-asyncio>=0.23.0",
+    "ruff>=0.6.0",
+    "twine>=5.0.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/glebulon/acevo-sdk"
+Issues = "https://github.com/glebulon/acevo-sdk/issues"
+Source = "https://github.com/glebulon/acevo-sdk"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+"acevo.catalogs" = ["data/*.json"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+
+[tool.ruff]
+line-length = 120
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+ignore = ["E501"]

acevo_sdk-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

acevo_sdk-0.1.0/src/acevo/__init__.py

@@ -0,0 +1,27 @@
+"""Python SDK for Assetto Corsa Evo telemetry and logs."""
+
+from .capture import CaptureMetadata, FrameData, RegionReader, TelemetryCapture
+from .decoder import decode_graphics, decode_physics, decode_static
+from .logs import LogParser
+from .models import InProgressLap, LapData, LapState, SessionData, StintData
+from .shared_session import SharedSessionManager
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "__version__",
+    "CaptureMetadata",
+    "FrameData",
+    "RegionReader",
+    "TelemetryCapture",
+    "decode_graphics",
+    "decode_physics",
+    "decode_static",
+    "LogParser",
+    "InProgressLap",
+    "LapData",
+    "LapState",
+    "SessionData",
+    "StintData",
+    "SharedSessionManager",
+]

acevo_sdk-0.1.0/src/acevo/_logging.py

@@ -0,0 +1,45 @@
+"""Internal logging helpers for acevo-sdk."""
+
+from __future__ import annotations
+
+import logging
+from enum import Enum
+from typing import Any
+
+
+class Component(Enum):
+    """Component identifiers used in SDK log records."""
+
+    LOG_PARSER = "LOG_PARSER"
+    TELEMETRY = "TELEMETRY"
+
+
+_logger = logging.getLogger("acevo")
+
+
+def _log(level: int, component: Component, message: str, **kwargs: Any) -> None:
+    if kwargs:
+        context = " ".join(f"{key}={value}" for key, value in kwargs.items() if value is not None)
+        if context:
+            message = f"{message} | {context}"
+    _logger.log(level, "[%s] %s", component.value, message)
+
+
+def log_debug(component: Component, message: str, **kwargs: Any) -> None:
+    _log(logging.DEBUG, component, message, **kwargs)
+
+
+def log_info(component: Component, message: str, **kwargs: Any) -> None:
+    _log(logging.INFO, component, message, **kwargs)
+
+
+def log_warning(component: Component, message: str, **kwargs: Any) -> None:
+    _log(logging.WARNING, component, message, **kwargs)
+
+
+def log_error(component: Component, message: str, **kwargs: Any) -> None:
+    _log(logging.ERROR, component, message, **kwargs)
+
+
+def log_exception(component: Component, message: str, exception: Exception, **kwargs: Any) -> None:
+    _logger.exception("[%s] %s | error=%s", component.value, message, exception, extra=kwargs or None)