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.
Requires Python: >=3.10
Keywords: cli, filesystem, directory, file-analysis, automation, python-cli, pathlib

**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
```bash
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:
```bash
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)**
```bash
python3 src/dirstats/dirstats_run.py <directory_path> [extensions...]
```

Examples:

Analyze all files in a directory:
```bash
python3 src/dirstats/dirstats_run.py /home/user/projects
```

Analyze only specific file extensions:
```bash
python3 src/dirstats/dirstats_run.py /home/user/projects py txt json
```

**Windows**
```bash
python src\dirstats\dirstats_run.py <directory_path> [extensions...]
```

Examples:

Analyze all files:
```bash
python src\dirstats\dirstats_run.py C:\Users\User\Documents
```

Analyze specific file extensions:
```bash
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**
---
```bash
.
├── 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.