<a href="https://www.fz-juelich.de/en/ice/ice-2"><img src="https://github.com/FZJ-IEK3-VSA/README_assets/blob/main/JSA-Header.svg?raw=True" alt="Forschungszentrum Juelich Logo" width="175px"></a>

# datadesclib 📊

A lightweight Python library to attach metadata to classes and functions using decorators and extract them into structured JSON/dictionary formats.

## Features

* **Zero Dependencies:** Uses only Python standard library (`inspect`, `json`, etc.).
* **Type Hint Support:** Automatically detects type annotations.
* **Docstring Fallback:** Uses docstrings as descriptions if no explicit metadata is provided.
* **Flexible:** Works with classes, methods, and global functions.

## Installation

```bash
pip install datadesclib
```

## Quick Start
### 1. Annotate your code
Use the @meta decorator to attach any custom information to your classes or functions.

```Python
from datadesclib import meta

@meta(author="Lukas", version="1.0", tags=["internal", "database"])
class UserData:
    name: str
    age: int = 25

    @meta(description="Saves the user to the DB")
    def save(self):
        pass
```

### 2. Extract Metadata
You can extract information from a single object or parse an entire Python file.

Extract from object:
```Python
from datadesclib import extract

info = extract(UserData)
print(info)
```
Parse a whole file to JSON:
```Python
from datadesclib import parser

json_data = parser("my_script.py")
print(json_data)
```

## License
[CC0 1.0 Universal (Public Domain)](LICENSE)

Copyright (c) 2026 FZJ-ICE-2

Developers: Celine Körner, Patrick Kuckertz, Johannes Jamroszczyk, Titan Hartono, Jann Weinand

## About Us

<p align="center"><a href="https://www.fz-juelich.de/en/ice/ice-2"><img src="https://raw.githubusercontent.com/FZJ-IEK3-VSA/README_assets/main/JSA-Header.svg" alt="Institut ICE-2"></a></p>
We are the <a href="https://www.fz-juelich.de/en/ice/ice-2">Institute of Climate and Energy Systems (ICE) - Jülich Systems Analysis</a> belonging to the <a href="https://www.fz-juelich.de/en">Forschungszentrum Jülich</a>. Our interdisciplinary department's research is focusing on energy-related process and systems analyses. Data searches and system simulations are used to determine energy and mass balances, as well as to evaluate performance, emissions and costs of energy systems. The results are used for performing comparative assessment studies between the various systems. Our current priorities include the development of energy strategies, in accordance with the German Federal Government’s greenhouse gas reduction targets, by designing new infrastructures for sustainable and secure energy supply chains and by conducting cost analysis studies for integrating new technologies into future energy market frameworks.

## Acknowledgements
The authors would like to thank the German Federal Government, the German State Governments, and the Joint Science Conference (GWK) for their funding and support as part of the NFDI4Ing consortium. Funded by the German Research Foundation (DFG) - project number: 442146713.

This work was also supported by the Helmholtz Association under the program "Energy System Design".

<a href="https://www.bmwk.de/Navigation/EN/Home/home.html"><img src="https://www.bmwk.de/SiteGlobals/BMWI/StyleBundles/Bilder/bmwi_logo_en.svg?__blob=normal&v=13" alt="BMWK Logo" width="130px"></a>