dfcleaner Documentation
dfcleaner is a lightweight Python utility for cleaning, parsing, and preparing time series and tabular datasets. It streamlines common DataFrame operations such as timezone normalization, date parsing, frequency inference, BOM removal, and value cleaning.
Installation
pip install dfcleaner
Or clone locally for development:
git clone https://github.com/BrandynHamilton/dfcleaner
cd dfcleaner
pip install -e .
Usage Example
from dfcleaner import DFCleaner
cleaner = DFCleaner(timezone="UTC")
df = cleaner.to_df("my_data.csv")
df, freq = cleaner.to_time(df)
df = cleaner.cleaning_values(df)
df = cleaner.clean_dates(df, time_freq=freq)
Core Methods
__init(timezone=None)
Accepts a string like 'UTC', 'US/Eastern', or any other valid IANA timezone string. If None, it removes timezone awareness from datetime index.
to_df(file, delimiter=',')
Load a CSV or Excel file into a clean pandas DataFrame.
- Handles BOM characters and whitespace.
- Removes rows that contain only invisible characters or whitespace.
apply_timezone(df)
Applies or removes timezone from the DataFrame index depending on the initialized setting.
detect_time_col(df, custom_col=None)
Scans DataFrame for common time-related column names. You can optionally pass a custom override.
to_time(df, time_col=None, dayfirst=False)
- Converts a detected or specified datetime column to the index.
- Infers the frequency of the datetime index.
- Returns the DataFrame with datetime index as well as the estimated frequency ('D','M','Q')
clean_dates(df, time_freq)
Drops incomplete periods based on inferred time frequency:
W: drops current week if incompleteM: drops current monthQ: drops current quarter
cleaning_values(df)
Cleans numeric object columns by:
- Removing symbols like
%,$,, - Replacing Excel artifacts like
#DIV/0!withNaN - Converting to proper numeric dtype
open_json(file_name)
Loads a JSON file and parses into a Python dictionary.
Project Structure
dfcleaner/
├── __init__.py
└── core.py
License
MIT License
Questions or Issues?
If you encounter any problems, have feature requests, or want to contribute improvements, feel free to reach out.
Email: [brandynham1120@gmail.com]
Metadata
Release files for dfcleaner 0.1.3
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| dfcleaner-0.1.3.tar.gz | 5.1 kB | Without provenance | Details for dfcleaner-0.1.3.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| dfcleaner-0.1.3-py3-none-any.whl | Python 3 | none | any | Details for dfcleaner-0.1.3-py3-none-any.whl |
Total release size: 10.4 kB
Release files / dfcleaner-0.1.3.tar.gz
| Download URL | dfcleaner-0.1.3.tar.gz |
|---|---|
| Size | 5.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
b0124c5bd44fc66e639146c9d87779e66a320af606534e71a2dce9751683a0a7
|
|
BLAKE2b-256 checksum How to use checksums |
6a8aa17d3c125949a52f3a52c6162c4590e9ffb9159847e3a264008802ad43fd
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.12.4
|
Release files / dfcleaner-0.1.3-py3-none-any.whl
| Download URL | dfcleaner-0.1.3-py3-none-any.whl |
|---|---|
| Size | 5.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
7d1985b868e817d557d316f0575979f305ff4c7a2a084002c112bce01d71d45c
|
|
BLAKE2b-256 checksum How to use checksums |
b99791c78677cb3512863b1bfa50adb85e3db47b379176c0425a55663ba4b1f8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.12.4
|
Security for dfcleaner 0.1.3
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.