Metadata-Version: 2.1
Name: preqs
Version: 0.1.0.dev1
Summary: A simple (and fast) requirements.txt file generator.
Author-email: "J. Berendt" <support@s3dev.uk>
License: 
        MIT License
        
        Copyright (c) 2024 | 73rd Street Development
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
        
Project-URL: Homepage, https://github.com/s3dev/preqs
Project-URL: Repository, https://github.com/s3dev/preqs
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: Microsoft :: Windows :: Windows 7
Classifier: Operating System :: Microsoft :: Windows :: Windows 10
Classifier: Operating System :: Microsoft :: Windows :: Windows 11
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Utilities
Requires-Python: >=3.6
Description-Content-Type: text/markdown
License-File: LICENSE

# A simple (and fast) requirements.txt file generator
The `preqs` project is a cross-platform, simple, fast and easy-to-use requirements file generator. Your project's imported dependencies are collected into a `requirements.txt` file. No more, no less.


## Installation
Installing `preqs` is quick and easy. As a design feature, the library does not have any external (non-built-in) dependencies.
```
pip install pipreqs
```

## Usage
The help (or usage) menu can be displayed, as below, using the following command from the terminal:
```
preqs --help
```
Which displays:
```
usage: preqs [PATH] [options]

A simple (and fast) requirements.txt file generator.

positional arguments:
  PATH                  Path to the project's root directory.
                        Alternatively, the path where the search for modules should start.
                        Defaults to the current directory.

options:
  -d, --debug           Print verbose debugging output while processing.
  -i IGNORE_DIRS [IGNORE_DIRS ...], --ignore_dirs IGNORE_DIRS [IGNORE_DIRS ...]
                        One or more director(y|ies) to be ignored when collecting module files.
  -p, --print           Print the detected requirements, rather than creating a file.
  -r, --replace         Replace the current requirements.txt file.
                        
  -h, --help            Display this help and usage, then exit.
  -v, --version         Display the version and exit.

preqs <installed version>
```


## Usage Example
In its simplest form, `preqs` can be run by just calling the program from within your project's root directory, without any arguments. The path from which the Python module discovery begins defaults to the *current directory*. If your project is in another directory, pass that directory's path into the `PATH` argument. The requirements file is saved into the path provided. 

**Notes:** 
- The following examples assume you are already in your project's root directory, therefore `PATH` is not provided.
- Any of the following flags may be combined to form your own requirements cocktail.

### Case 1: Simplest form
Simply generate a requirements file for your project, as:

1. Run `preqs` as:
```bash
preqs
``` 
2. Check the current directory for a `requirements.txt` file containing the project's external dependencies.

### Case 2: Ignoring directories
If you wish to exclude a directory (or directories) from the requirements file, the `--ignore_dirs` flag may be used as:

1. Run `preqs` as:
```bash
preqs --ignore_dirs docs build
```
2. Check the current directory for a `requirements.txt` file containing the project's external dependencies.

### Case 3: Display only (do not generate a file)
In some cases, for example with an existing requirements file you do not want to overwrite, you may wish to *display* the requirements to the terminal. This can be accomplished using the `--print` flag, as:

1. Run `preqs` as:
```bash
preqs --print
```
2. Watch the terminal for an output displaying the project's requirements.

### Case 4: Overwrite an existing requirements file
By default, if a `requirements.txt` file exists, you will be alerted. The existing file will *not* be overwritten. That is, unless you tell `preqs` it's OK.

1. Run `preqs` as:
```bash
preqs --replace
```
2. Check the current directory for a *new* `requirements.txt` file containing the project's external dependencies.


## Additional information

### How is the version number obtained?
The version number you see in the requirements file output is obtained using the built-in `importlib` library. Therefore, the package *must be installed* in the environment being used to run `preqs`.

- By design, we do *not* use PyPI to obtain version numbers as this practice usually involves assuming the latest version - whereas this may not be the case for your project.
- Any packages which are known to be imported by the project, and yet do not appear in the requirements file, *may not be installed*. Run `preqs` with the `--print` flag to observe any packages which are imported for which the version number could not be obtained. These are ignored when the requirements file is written.

### I don't see a specific package in the requirements file
Refer to the *How is the version number obtained?* question.

### Why should I not just use `pip freeze`?
Many online 'tutorials' for generating a requirements file say to use `pip freeze` and redirect the output to a file called `requirements.txt`. However, this is not good practice for the following reasons:

- *All* of the packages installed in your development environment will be listed in the requirements file. This may include some (or many) packages which your project does not require, thus bloating the end-user's installation and thereby cluttering their environment. Or, the packages you have in your environment, although not used by the project, may be out-of-date; causing the end-user to be forced to install out-of-date packages.
- A true requirements file should contain *only* those packages which are imported and required by the project.
- Only the packages that were installed with `pip install` will be included in the requirements file.

