dirstats 1.0.1

Analyze a base directory and calculate the total number of files, subfolders, and overall directory size, with optional filtering by one or more file extensions.

DirStats

dirstats is a lightweight command-line utility written in Python for analyzing directory structures. It reports the total number of files, subfolders, and the aggregate size of a directory, with optional filtering by one or more file extensions.

Built entirely with Python’s standard library, it is fast, portable, and easy to integrate into automation workflows.

Overview

dirstats recursively scans a base directory and collects useful statistics:

• Number of files
• Number of subdirectories
• Total size of files (Bytes, KB, MB, GB)
• Optional filtering by file extension(s)
• It is designed as a small, reusable CLI tool, ideal for:
• File system analysis
• Automation scripts
• Backend utilities
• Data preprocessing
• Learning and teaching filesystem traversal with Python

Installation

Unix / Linux / macOS / Windows

pip install dirstats

After installation, the dirstats command will be available globally.

Usage

Analyze all files in a directory

• dirstats /path/to/directory

Analyze only specific file extensions

• dirstats /path/to/directory py txt md

Analyze all files explicitly

• dirstats /path/to/directory "*"

Alternative Installation (Without pip)

If you prefer not to install dirstats via pip, you can run it directly from the source code by cloning or downloading the repository.

1. Clone or Download the Project

Using Git:

git clone https://github.com/Sharrrkkk/DirStats
cd dirstats

Or download the ZIP from GitHub and extract it. Make sure you have Python 3.10 or higher installed.

Usage Without Installation

The CLI tool can be executed directly using Python by running the main script.

Linux / macOS (Unix-like systems)

python3 src/dirstats/dirstats_run.py <directory_path> [extensions...]

Examples:

Analyze all files in a directory:

python3 src/dirstats/dirstats_run.py /home/user/projects

Analyze only specific file extensions:

python3 src/dirstats/dirstats_run.py /home/user/projects py txt json

Windows

python src\dirstats\dirstats_run.py <directory_path> [extensions...]

Examples:

Analyze all files:

python src\dirstats\dirstats_run.py C:\Users\User\Documents

Analyze specific file extensions:

python src\dirstats\dirstats_run.py C:\Users\User\Documents py txt json

How It Works (Algorithm Overview)

1. Parse CLI arguments

• Base directory path
• Optional file extensions

2. Traverse the directory recursively

• Uses pathlib.Path.glob("**/*")

3. Filter files (if extensions are provided)

4. Collect statistics

• File count
• Subfolder count (All folders, and if one or more extensions were specified, only folders containing files matching those extensions)
• Total file size

5. Display results

• Multiple size units for readability

All operations rely exclusively on Python’s standard library.

Features

• Recursive directory traversal
• Extension-based file filtering
• Accurate size calculation
• Clear CLI output
• No external dependencies
• Cross-platform support
• Minimal and readable codebase

Project Structure

.
├── LICENSE
├── README.md
├── pyproject.toml
└── src
    └── dirstats
        ├── __about__.py
        ├── __init__.py
        └── dirstats_run.py

Notes

• When filtering by file extensions, only subfolders containing matching files are counted. If no filter is used (i.e., no arguments for extensions or using "*"), all subfolders in the base directory are counted.

• File extensions must be passed without periods (py, not .py).

• To analyze the entire base directory, you don't need to specify extensions or use "", but you can use "" to analyze all files without filtering if you want to be more explicit. However, omitting extensions serves the same purpose as using "*".

• Designed for use with the command line, but it can be imported and extended if needed.

License

• This project is licensed under the MIT License.