Skip to main content

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 incomplete
  • M: drops current month
  • Q: drops current quarter

cleaning_values(df)

Cleans numeric object columns by:

  • Removing symbols like %, $, ,
  • Replacing Excel artifacts like #DIV/0! with NaN
  • 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)

Source distribution for dfcleaner 0.1.3
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)

Table of built distributions (wheels) for dfcleaner 0.1.3
File Interpreter ABI Platform Actions
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.

Release history Release notifications | RSS feed

This release

0.1.3 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page