Merge pull request #11 from PieceWiseProjects/feature/standardize-codebase

feat: standardize codebase and fix documentation for v1.0.2

Author: RoyAalekh

.gitignore

@@ -179,5 +179,56 @@ __pycache__
 *.egg-info
 aws
 *.egg
-.iml
+*.iml
+
+# Project-specific test files
+test_*.py
+temp_*.py
+example_*.py
+
+# Animation and media files (keep Animation.gif but exclude others)
+*.mp4
+*.mov
+*.avi
+
+# Temporary and backup files
+*.tmp
+*.temp
+*.bak
+*.swp
+*~
+
+# macOS specific
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+
+# Windows specific
+Thumbs.db
+ehthumbs.db
+Desktop.ini
+
+# VS Code
+.vscode/
+*.code-workspace
+
+# PyCharm (uncommented for safety)
+.idea/
+
+# Additional coverage and linting
+.ruff_cache/
+.mypy_cache/
+htmlcov/
+.coverage*
+
+# Build and dist artifacts
+build/
+dist/
+*.egg-info/
+
+# Documentation build
+docs/_build/
+docs/build/
 

.pre-commit-config.yaml

@@ -0,0 +1,45 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.4.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-added-large-files
+      - id: check-merge-conflict
+      - id: debug-statements
+
+  - repo: https://github.com/psf/black
+    rev: 23.12.1
+    hooks:
+      - id: black
+        language_version: python3.9
+
+  - repo: https://github.com/pycqa/isort
+    rev: 5.13.2
+    hooks:
+      - id: isort
+        args: ["--profile", "black"]
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.1.8
+    hooks:
+      - id: ruff
+        args: [--fix, --exit-non-zero-on-fix]
+
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.7.1
+    hooks:
+      - id: mypy
+        additional_dependencies: [types-all]
+        args: [--strict, --ignore-missing-imports]
+
+  - repo: local
+    hooks:
+      - id: pytest
+        name: pytest
+        entry: uv run pytest
+        language: system
+        types: [python]
+        pass_filenames: false
+        always_run: true

README.md

@@ -1,8 +1,8 @@
-# 🕒 formatify
+# formatify
 
 ---
 
-> 🧠 Auto-detect and standardize messy timestamp formats.
+> Auto-detect and standardize messy timestamp formats.
 > Perfect for log parsers, data pipelines, or anyone tired of wrestling with inconsistent datetime strings.
 
 [![PyPI version](https://img.shields.io/pypi/v/formatify_py.svg)](https://pypi.org/project/formatify_py)
@@ -20,7 +20,7 @@
 
 ---
 
-## ⚠️ Problem
+## Problem
 
 Ever pulled in a CSV or log file and found timestamps like this?
 
@@ -36,7 +36,7 @@ How do you reliably infer and **standardize** them — especially when:
 
 ---
 
-## ✅ Solution
+## Solution
 
 `formatify` infers the datetime format(s) from a list of timestamp strings and gives you:
 
@@ -49,7 +49,7 @@ No dependencies. Works out of the box.
 
 ---
 
-## 📄 What This Library Does
+## What This Library Does
 
 Behind the scenes, `formatify` uses:
 
@@ -68,10 +68,10 @@ It produces:
 
 ---
 
-## 🚀 Quick Example
+## Quick Example
 
 ```python
-from formatify_py.main import analyze_heterogeneous_timestamp_formats
+from formatify_py import analyze_heterogeneous_timestamp_formats
 
 samples = [
     "2023-07-15T14:23:05Z",
@@ -90,19 +90,19 @@ for gid, group in results.items():
 
 ---
 
-## 🔍 Features
+## Features
 
-✅ Auto-detect `strftime` format
-✅ Handles ISO 8601, text months, UNIX epoch
-✅ Infers year/month/day/hour/minute roles
-✅ Groups mixed formats automatically
-✅ Timezone-aware
-✅ No dependencies
-✅ Fast and customizable
+- Auto-detect `strftime` format
+- Handles ISO 8601, text months, UNIX epoch
+- Infers year/month/day/hour/minute roles
+- Groups mixed formats automatically
+- Timezone-aware
+- No dependencies
+- Fast and customizable
 
 ---
 
-## 🧪 API
+## API
 
 ### Main Entry Point
 
@@ -120,6 +120,9 @@ Returns a dictionary mapping group IDs to result dictionaries. Each result inclu
 * `detected_timezone`: parsed offset (if any)
 * `coverage`: fraction of total samples in this group
 * `accuracy`: percent of valid parses in group
+* `primary_delimiter`: most common delimiter used
+* `samples`: original timestamps in this group
+* `group_features`: detected structural features
 
 ### Lower-Level Functions
 
@@ -131,7 +134,7 @@ infer_datetime_format_from_samples(samples: List[str]) -> Dict[str, Any]
 
 ---
 
-## 🔊 Mixed Format Handling
+## Mixed Format Handling
 
 `formatify` is designed to handle **real-world timestamp mess**. When your input includes a mix of styles — ISO, slashed, text-months, or epoch — it:
 
@@ -143,20 +146,20 @@ This lets you feed in 3 formats or 30, and still get clean, grouped results.
 
 ---
 
-## 👁️ Design Notes
+## Design Notes
 
 Want to know how the internals work? Check out:
 
 * [How Formatify Thinks About Timestamps](docs/design.md)
 
 ---
 
-## 🔍 Dev Guide
+## Dev Guide
 
 ```bash
 # Clone the repo
 git clone https://github.com/PieceWiseProjects/formatify.git
-cd formatify_py
+cd formatify
 
 # Set up environment
 uv pip install -e .[dev,test]
@@ -173,26 +176,26 @@ uv run python -m build
 
 ---
 
-## 🚰 Contributing
+## Contributing
 
 We're just getting started — contributions, issues, and ideas welcome!
 
 1. Fork and branch: `git checkout -b feature/my-feature`
 2. Code and test
 3. Lint and push
-4. Open a pull request 💡
+4. Open a pull request
 
 Follow our [Contributor Guidelines](https://www.contributor-covenant.org).
 
 ---
 
-## 📜 License
+## License
 
 MIT — see [LICENSE](LICENSE) for details.
 
 ---
 
-## 🙌 Credits
+## Credits
 
 Built and maintained by [Aalekh Roy](https://github.com/RoyAalekh)
 Part of the [PieceWiseProjects](https://github.com/PieceWiseProjects) initiative.

docs/design.md

@@ -4,7 +4,7 @@ Just a quick note on how the core logic of `formatify` works, what design choice
 
 ---
 
-## 🧭 Why This Exists
+## Why This Exists
 
 Parsing timestamps in the wild is messy:
 
@@ -16,7 +16,7 @@ So we built something lean and explicit — especially useful for logs, ETL pipe
 
 ---
 
-## ✅ What We Chose To Do
+## What We Chose To Do
 
 * Use **regex + tokenization** instead of fuzzy parsing
 * Look at **how often parts change** (e.g., days vs. years) to guess roles
@@ -32,7 +32,7 @@ And we return:
 
 ---
 
-## 💡 What We Didn’t Use
+## What We Didn't Use
 
 We intentionally skipped tools like:
 
@@ -42,23 +42,23 @@ We intentionally skipped tools like:
 
 ---
 
-## 📉 Tradeoffs
+## Tradeoffs
 
-👍 Pros:
+Pros:
 
 * Fast
 * Easy to reason about
 * Plays nice with your data pipeline
 
-👎 Cons:
+Cons:
 
 * No locale support (e.g. `1 Mars 2023`)
 * Not built for unstructured natural language
 * Not a fuzzy parser — it’s deterministic
 
 ---
 
-## 🧱 How It All Fits Together
+## How It All Fits Together
 
 ```mermaid
 graph TD
@@ -74,7 +74,7 @@ graph TD
 
 ---
 
-## 🧠 TL;DR
+## TL;DR
 
 `formatify` is built to be: