AgoraData (ἀγορά - gathering place) brings order to your data, scripts, and projects. Inspired by the ancient Greek Agora—a central public space where citizens organized society—this library provides elegant tools for structuring your work environment without external dependencies.
$ pip install agoradataFrom source:
$ git clone https://github.com/ogkae/agoradata.git
$ cd agoradata
$ pip install -e .With CLI support:
$ pip install agoradata[cli]from agoradata import DataOrganizer, ScriptBeautifier, ProjectManager
# organize data
organizer = DataOrganizer()
sorted_data = organizer.sort_dict({"banana": 3, "apple": 4}, by_key=True)
# beautify code
beautifier = ScriptBeautifier()
clean_code = beautifier.beautify_script("def hello():\n print('world')")
# manage projects
manager = ProjectManager()
manager.register_project(
name="my_project",
path="/path/to/project",
description="My awesome project"
)| module | description | key functions |
|---|---|---|
core.data |
recursive sorting, merging, flattening | sort_dict(), merge_dicts(), flatten_list() |
core.normalize |
key/value normalization | normalize_dict(), to_snake_case(), to_camel_case() |
core.filter |
data filtering by criteria | filter_keys(), filter_values(), filter_by_type() |
core.stats |
statistical calculations | mean(), median(), mode(), frequency() |
formatting.script |
code beautification | beautify_script(), validate_syntax(), get_imports() |
formatting.markdown |
markdown generation | dict_to_table(), generate_toc(), add_badge() |
project |
project management | register_project(), clone_project(), list_projects() |
io.file_utils |
file operations | read_file(), write_file(), copy_dir() |
sort_list(lst, key=None, reverse=False) -> listSort lists with optional key function.
sort_dict(d, by_key=True, recursive=False) -> dictSort dictionaries by key or value. Supports recursive nested structures.
sort_list_recursive(lst) -> listRecursively sort nested lists.
merge_dicts(*dicts, deep=True) -> dictDeep merge multiple dictionaries.
flatten_list(lst, depth=None) -> listFlatten nested lists with depth control.
Example:
from agoradata import DataOrganizer
org = DataOrganizer()
# nested sorting
data = {"z": [3, 1, 2], "a": {"y": 5, "x": 4}}
sorted_data = org.sort_dict(data, recursive=True)
# merge with deep nesting
result = org.merge_dicts(
{"a": {"b": 1}},
{"a": {"c": 2}},
deep=True
) # {"a": {"b": 1, "c": 2}}normalize_key(key, style="snake_case") -> strNormalize key names (snake_case, camelCase).
normalize_dict(d, key_style="snake_case", remove_empty=False) -> dictNormalize entire dictionary structure.
to_snake_case(text) -> str
to_camel_case(text) -> strString case conversion utilities.
Example:
from agoradata import DataNormalizer
normalizer = DataNormalizer()
# normalize keys
data = {"UserName": "alice", "user_age": 25}
normalized = normalizer.normalize_dict(data, key_style="snake_case")
# {"user_name": "alice", "user_age": 25}filter_keys(d, keys, keep=True) -> dictFilter dictionary by key whitelist/blacklist.
filter_values(d, predicate) -> dictFilter by value predicate function.
filter_by_type(data, target_type) -> listExtract values of specific type.
Example:
from agoradata import DataFilter
filter = DataFilter()
# keep only specific keys
data = {"name": "alice", "age": 25, "email": "alice@example.com"}
filtered = filter.filter_keys(data, ["name", "age"])
# filter by predicate
numbers = {"a": 1, "b": 2, "c": 3, "d": 4}
evens = filter.filter_values(numbers, lambda x: x % 2 == 0)mean(lst) -> float
median(lst) -> float
mode(lst) -> AnyCalculate statistical measures.
frequency(lst) -> dict
unique_count(lst) -> intCount and frequency analysis.
Example:
from agoradata import DataStats
stats = DataStats()
numbers = [1, 2, 2, 3, 3, 3, 4]
print(stats.mean(numbers)) # 2.57
print(stats.median(numbers)) # 3
print(stats.mode(numbers)) # 3
print(stats.frequency(numbers)) # {1: 1, 2: 2, 3: 3, 4: 1}beautify_script(
code_str,
tab_size=4,
use_tabs=False,
sort_imports=True,
max_line_length=79
) -> strFormat Python code with PEP8 compliance.
validate_syntax(code_str) -> bool
get_imports(code_str) -> dictSyntax validation and import extraction.
Example:
from agoradata import ScriptBeautifier
beautifier = ScriptBeautifier()
code = """
import os
from typing import Dict
import sys
def hello():
x=1+2
print('hello')
"""
clean = beautifier.beautify_script(code, sort_imports=True)
# imports sorted: stdlib → typing → local
# proper indentation applieddict_to_table(d, headers=None) -> str
list_to_table(lst, headers=None) -> strConvert data structures to markdown tables.
generate_toc(headers, max_depth=3) -> strGenerate table of contents.
data_to_markdown(data, title=None) -> str
add_badge(text, style="info") -> strExport data and add badges.
Example:
from agoradata import MarkdownFormatter
formatter = MarkdownFormatter()
# data to table
data = {"name": "alice", "role": "admin", "age": 25}
table = formatter.dict_to_table(data)
# generate TOC
headers = ["Introduction", "Setup", "Usage", "API"]
toc = formatter.generate_toc(headers)register_project(name, path, description="", tags=None, metadata=None) -> NoneRegister project in local database.
list_projects() -> list
get_project(name) -> dict
search_projects(query) -> listQuery and search projects.
clone_project(source_path, dest_path, beautify=True, restructure=False) -> NoneClone and optionally improve project structure.
Example:
from agoradata import ProjectManager
manager = ProjectManager()
# register
manager.register_project(
name="web_api",
path="/projects/web_api",
tags=["python", "flask", "api"]
)
# search
results = manager.search_projects("api")
# clone with beautification
manager.clone_project(
"/source/project",
"/dest/project",
beautify=True,
restructure=True
)
manager.close()from agoradata import (
DataOrganizer,
DataNormalizer,
DataFilter,
DataStats
)
# raw data
raw_data = {
"UserName": "alice",
"user_age": 25,
"UserEmail": "alice@example.com",
"empty_field": "",
"score": 85
}
# normalize
normalizer = DataNormalizer()
normalized = normalizer.normalize_dict(raw_data, remove_empty=True)
# filter
filter = DataFilter()
user_info = filter.filter_keys(normalized, ["user_name", "user_age"])
# organize
organizer = DataOrganizer()
sorted_info = organizer.sort_dict(user_info)
print(sorted_info)
# {"user_age": 25, "user_name": "alice"}from agoradata import ScriptBeautifier, FileUtils
from pathlib import Path
beautifier = ScriptBeautifier()
file_utils = FileUtils()
# beautify all python files in directory
project_path = Path("/path/to/project")
for py_file in project_path.rglob("*.py"):
if file_utils.is_python_file(py_file):
code = file_utils.read_file(py_file)
beautified = beautifier.beautify_script(code)
file_utils.write_file(py_file, beautified)
print(f"Beautified: {py_file}")from agoradata import MarkdownFormatter, DataStats
formatter = MarkdownFormatter()
stats = DataStats()
# sample data
sales_data = [100, 150, 120, 180, 200, 190]
# generate report
report = f"""
# Sales Report
## Statistics
{formatter.dict_to_table({
"Mean": stats.mean(sales_data),
"Median": stats.median(sales_data),
"Total": sum(sales_data)
})}
## Summary
{formatter.add_badge("Status: Complete", "success")}
"""
print(report)# sort json data
$ agoradata sort data.json --by-key --recursive -o sorted.json
# beautify python script
$ agoradata beautify script.py --tab-size 4 --max-line-length 79
# convert data to markdown
$ agoradata markdown data.json -o README.md --title "Data Report"# sort command
--by-key # sort by keys
--by-value # sort by values
--recursive # recursive sorting
-o, --output # output file
# beautify command
--tab-size INT # spaces per indent (default: 4)
--use-tabs # use tabs instead of spaces
--max-line-length INT # max line length (default: 79)
# markdown command
--title TEXT # document title
-o, --output # output fileRun tests:
$ python -m pytest tests/Or with unittest:
$ python -m unittest discover tests- Python 3.7+
- No external dependencies (stdlib only)
- Optional:
clickfor CLI (pip install agoradata[cli]) - Optional:
pyyamlfor YAML config
see LICENSE for details.
Contributions welcome! Please submit a Pull Request.
Priority areas:
- Enhanced data validation
- More export formats (CSV, YAML, TOML)
- Plugin system for custom formatters
- Performance optimization for large datasets
- Comprehensive test coverage