scandirx 0.1.0

A fast, recursive directory scanner using a C extension.

scandirx

scandirx is a fast and efficient directory walker implemented as a Python package with a C extension. It allows you to recursively traverse directories and collect all file and folder paths with optional depth control.

Table of Contents

• Installation
  • Prerequisites
  • Clone the Repository
  • Set Up a Virtual Environment
  • Install Dependencies
  • Build and Install the Package
• Usage
  • Basic Example
• Running Tests
• Contributing
• License

Installation

Follow these steps to set up scandirx on your local machine.

Prerequisites

• Python 3.6 or higher
• C Compiler: Ensure you have a C compiler installed.
  • Ubuntu/Debian:

    sudo apt-get update
    sudo apt-get install build-essential python3-dev
    

  • macOS:

    xcode-select --install
    

  • Windows:
    • Install Build Tools for Visual Studio.

Clone the Repository

First, clone the repository to your local machine:

git clone https://github.com/titangmz/scandirx.git
cd scandirx

Set Up a Virtual Environment

It's recommended to use a virtual environment to manage dependencies:

python3 -m venv .venv

Activate the virtual environment:

• Linux/macOS:

  source .venv/bin/activate
  

• Windows:

  .venv\Scripts\activate
  

Install Dependencies

Install the required Python packages using pip:

pip install -r requirements.txt

Build and Install the Package

Build the C extension and install the package in editable mode:

pip install -e .

This command will compile the C extension and install the scandirx package into your virtual environment.

Alternatively, you can build the extension in place:

python setup.py build_ext --inplace

This will place the compiled _scandirx extension directly into the scandirx package directory.

Usage

Once installed, you can use scandirx to walk through directories.

Basic Example

import scandirx

# Walk through the specified directory with a maximum depth of 2
directories = scandirx.walk("/path/to/your/directory", max_depth=2)

# Print all found directories and files
print(*directories, sep="\n")

Example Output:

/path/to/your/directory/file1.txt
/path/to/your/directory/subdir1/
path/to/your/directory/subdir1/file2.txt
...

Running Tests

Ensure that scandirx is working correctly by running the provided tests.

1. Activate the Virtual Environment (if not already activated):

   source .venv/bin/activate  # Linux/macOS
   .venv\Scripts\activate     # Windows
   

2. Run Tests Using pytest:

   pytest
   

   You should see output indicating that all tests have passed.

Contributing

Contributions are welcome! Please follow these steps to contribute:

1. Fork the Repository

2. Create a New Branch:

   git checkout -b feature/your-feature-name
   

3. Make Your Changes

4. Commit Your Changes:

   git commit -m "Add your message here"
   

5. Push to Your Fork:

   git push origin feature/your-feature-name
   

6. Create a Pull Request

Please ensure that your code follows the project's coding standards and that all tests pass before submitting a pull request.

License

This project is licensed under the MIT License.

---

© 2023 Pedram Parsa