How corsosource/birdsong works
Project type and purpose
• Birdsong is an open-source Python client library that wraps the Canary Labs Historian REST API, making it easy to send and receive time-series (“tag”) data.
• It is _not_ a front-end or standalone service; it’s a helper library for other Python code (or Ignition scripts) to interact with the Canary historian.
File structure
• Top-level:
• setup.py (packaging script)
• README.md (usage and architecture narrative)
• birdsong/ (the Python package containing all logic)
• test/ (a Jupyter notebook for manual/integration tests)
• birdsong/ modules:
• rest.py – low-level HTTP wrapper (handles GET/POST, SSL options)
• tokens.py – obtains and refreshes Canary session/user tokens
• sender.py – high-level “CanarySender” class for writing data (createNewFile, storeData, fileRollover)
• view.py – high-level “CanaryView” class for querying data (browseNodes, getTagData, getLiveData, etc.)
• values.py – helper data structures (Tvq, Property, Annotation) and their serialization/validation
• __init__.py – public API exports
Extract architectural hints from the README
• Uses Python context-managers to open/close tokenized HTTP sessions.
• Follows a layered approach:
a. values.py defines data models
b. rest.py/tokens.py implement communication primitives
c. sender.py/view.py orchestrate domain operations
1) Client Application (could be any Python script, Ignition module, or notebook that does import birdsong)
2) birdsong Library
– Values Module (Tvq, Annotation, Property structures)
– REST Module (HTTP calls, SSL handling)
– Token Manager (login, refresh flow)
– Sender (storeData, createNewFile, fileRollover)
– View (browseNodes/Tags/Status, getTagData, getLiveData, getQualities/Aggregates/Properties)
3) External Canary API (REST endpoints for view & sender services)
4) Canary Historian Server (backend that persists data to its database)
6) Tests (Jupyter notebook referencing birdsong)
• Client App → birdsong API (entry points in __init__.py)
• Sender/View → Token Manager to acquire JWT/session tokens
• Sender/View → REST Module to issue HTTP calls (attach tokens)
• REST Module → Canary API endpoints over HTTPS (POST/GET)
• Canary API → Historian backend → responds with JSON
• REST Module → passes JSON up → Sender/View parse into Python objects (using values.py)
• Tests → Client App / birdsong
c. Architectural patterns & design principles:
• Layered architecture (data models → transport → domain operations)
• Context-manager pattern for automatic resource cleanup
• Generator pattern in view.py for streaming large datasets
• Single Responsibility principle: each module has a focused purpose
• Retry & token-refresh logic encapsulated in tokens.py
d. Key technologies & frameworks:
• Python 3.x
• requests (HTTP client)
• Canary REST API (external service)
• Jupyter (for integration tests in test/)