Skip to content

Add Detailed Documentation for pip-upgrader #57

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Add Detailed Documentation for pip-upgrader #57

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
258 changes: 210 additions & 48 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,76 +1,238 @@
**Currently unmaintained, I'm using [poetry](https://python-poetry.org/) for all my projects, but i'm happy to review and release PRs**


# pip-upgrader [![Build Status](https://travis-ci.org/simion/pip-upgrader.svg?branch=master)](https://travis-ci.org/simion/pip-upgrader)

An interactive pip requirements upgrader. Because upgrading
requirements, package by package, is a pain in the ass. It also updates
the version in your requirements.txt file.

## Purpose

This cli tools helps you interactively(or not) upgrade packages from
requirements file, and also **update the pinned version from
requirements file(s)**.

If no requirements are given, the command **attempts to detect the
requirements file(s)** in the current directory.
An interactive pip requirements upgrader. Because upgrading requirements, package by package, is a pain in the ass. It also updates the version in your requirements.txt file.

**Note**: Currently unmaintained. I'm using [poetry](https://python-poetry.org/) for all my projects, but I'm happy to review and release PRs.

## Table of Contents
- [Overview](#overview)
- [Installation](#installation)
- [Usage](#usage)
- [Basic Usage](#basic-usage)
- [Specifying Requirements Files](#specifying-requirements-files)
- [Skipping the Interactive Prompt](#skipping-the-interactive-prompt)
- [Including Prerelease Versions](#including-prerelease-versions)
- [Dry Run Mode](#dry-run-mode)
- [Skipping Package Installation](#skipping-package-installation)
- [Skipping Virtual Environment Check](#skipping-virtual-environment-check)
- [Using Default Index URL](#using-default-index-url)
- [Using pip-upgrader with setup.py](#using-pip-upgrader-with-setuppy)
- [Examples](#examples)
- [Auto-Discovery of Requirements Files](#auto-discovery-of-requirements-files)
- [Upgrading Specific Packages](#upgrading-specific-packages)
- [Upgrading All Packages Without Prompting](#upgrading-all-packages-without-prompting)
- [Including Prerelease Versions](#including-prerelease-versions-example)
- [FAQ](#faq)
- [Contributing](#contributing)
- [License](#license)

## Overview

`pip-upgrader` is a command-line utility designed to ease the process of upgrading Python packages in your project. It allows for both interactive and non-interactive upgrading of packages listed in your requirements files and automatically updates the pinned versions in those files.

This tool helps automate the often tedious task of upgrading packages, ensuring your project dependencies are up to date with minimal effort. The interactive mode prompts you to upgrade each package individually, while the non-interactive mode can batch upgrade all selected packages.

Quick preview:

![image](https://github.com/simion/pip-upgrader/master/demo.gif)

### Key Features

- **Interactive Mode**: Upgrade packages with a prompt that allows you to select which packages to upgrade.
- **Automatic Requirements Update**: Automatically updates the version numbers in your `requirements.txt` or other specified requirements files.
- **Batch Upgrading**: Allows upgrading of all or specific packages in a batch mode.
- **Dry Run Mode**: Provides a simulation of the upgrade process without making any actual changes.
- **Prerelease Support**: Allows inclusion of prerelease versions when upgrading packages.
- **Multiple Requirements Files**: Supports upgrading from multiple requirements files simultaneously.

## Installation

pip install pip-upgrader
To install `pip-upgrader`, use the following command:

```bash
pip install pip-upgrader
```

**Note**: Installing `pip-upgrader` will also install the following dependencies:
- `docopt`
- `packaging`
- `requests`
- `terminaltables`
- `colorclass`

**Note:** this packages installs the following requirements: `'docopt',
'packaging', 'requests', 'terminaltables', 'colorclass'`
If you wish to avoid installing these dependencies in your project's virtual environment, consider installing `pip-upgrader` globally on your system. To upgrade `pip-upgrader`, run:

To avoid installing all these dependencies in your project, you can
install `pip-upgrader` in your system, rather than your virtualenv. If
you install it in your system, and need to upgrade it, run `pip install
-U pip-upgrader`
```bash
pip install -U pip-upgrader
```

## Usage

**Activate your virtualenv** (important, because it will also install
the new versions of upgraded packages in current virtualenv)
### Basic Usage

To begin using `pip-upgrader`, activate your virtual environment and navigate to your project directory. Then run:

```bash
pip-upgrade
```

This command will automatically detect any requirements files in your current directory and prompt you to select which packages you would like to upgrade.

### Specifying Requirements Files

If you need to upgrade packages listed in specific requirements files, you can specify these files as positional arguments:

```bash
pip-upgrade requirements.txt
pip-upgrade requirements/dev.txt requirements/production.txt
```

### Skipping the Interactive Prompt

**CD into your project.** Then: :
If you already know which packages you want to upgrade, you can skip the interactive prompt by specifying the packages with the `-p` option:

$ pip-upgrade
```bash
pip-upgrade requirements.txt -p django -p celery
```

To upgrade all packages without any prompts, use:

```bash
pip-upgrade requirements.txt -p all
```

### Including Prerelease Versions

To include prerelease versions when upgrading your packages, use the `--prerelease` option:

```bash
pip-upgrade --prerelease
```

This option is particularly useful if you want to test your project with the latest prerelease versions of your dependencies.

### Dry Run Mode

Arguments: :
To simulate the upgrade process without making any actual changes to your environment or requirements files, use the `--dry-run` option:

requirements_file(s) The requirement FILE, or WILDCARD PATH to multiple files. (positional arguments)
--prerelease Include prerelease versions for upgrade, when querying pypi repositories.
-p <package> Pre-choose which packages tp upgrade. Skips any prompt.
--dry-run Simulates the upgrade, but does not execute the actual upgrade.
--skip-package-installation Only upgrade the version in requirements files, don't install the new package.
--skip-virtualenv-check Disable virtualenv check. Allows installing the new packages outside the virtualenv.
--use-default-index Skip searching for custom index-url in pip configuration file(s).
```bash
pip-upgrade --dry-run
```

This allows you to review which packages would be upgraded without committing to any changes.

### Skipping Package Installation

If you want to update the versions in your requirements files without actually installing the new versions of the packages, use the `--skip-package-installation` option:

```bash
pip-upgrade --skip-package-installation
```

This is useful if you want to update your requirements files first and install the packages later.

Examples:
### Skipping Virtual Environment Check

pip-upgrade # auto discovers requirements file. Prompts for selecting upgrades
pip-upgrade requirements.txt
pip-upgrade requirements/dev.txt requirements/production.txt
By default, `pip-upgrader` checks whether you're working inside a virtual environment to prevent installing packages globally by mistake. To disable this check and allow installation outside of a virtual environment, use the `--skip-virtualenv-check` option:

# skip prompt and manually choose some/all packages for upgrade
pip-upgrade requirements.txt -p django -p celery
pip-upgrade requirements.txt -p all
```bash
pip-upgrade --skip-virtualenv-check
```

# include pre-release versions
pip-upgrade --prerelease
### Using Default Index URL

To use `pip-upgrader` on install requirements located in a `setup.py`
file, try this:
If you want to skip searching for a custom index URL in pip configuration files and use the default PyPI index, use the `--use-default-index` option:

```bash
pip-upgrade --use-default-index
```

``` sh
### Using pip-upgrader with setup.py

To upgrade packages listed in a `setup.py` file, you can use the following commands:

```bash
./setup.py egg_info
pip-upgrade $(./setup.py --name | tr -- - _)*.egg-info/requires.txt
```

This will display any versions that can be upgraded, and helps you to
manually main
This approach will display any versions that can be upgraded, helping you to manually maintain the dependencies specified in `setup.py`.

## Examples

### Auto-Discovery of Requirements Files

Running `pip-upgrade` without any arguments will automatically detect requirements files in the current directory and prompt you for upgrades:

```bash
pip-upgrade
```

### Upgrading Specific Packages

To upgrade only selected packages, specify the packages with the `-p` option:

```bash
pip-upgrade requirements.txt -p django -p celery
```

### Upgrading All Packages Without Prompting

To upgrade all packages listed in your requirements files without any interactive prompts:

```bash
pip-upgrade requirements.txt -p all
```

### Including Prerelease Versions Example

To include prerelease versions of packages during the upgrade process:

```bash
pip-upgrade --prerelease
```

This is useful if you want to work with the latest prerelease versions available on PyPI.

## FAQ

**Q: Can I use `pip-upgrader` in projects without a requirements file?**

A: Yes, `pip-upgrader` attempts to detect `requirements.txt` or similar files in your current directory. If no files are found, it will not perform any upgrades.

**Q: What happens if I run `pip-upgrader` outside of a virtual environment?**

A: By default, `pip-upgrader` checks whether you're inside a virtual environment to avoid global package installations. However, you can bypass this check using the `--skip-virtualenv-check` option.

**Q: How do I know which packages are safe to upgrade?**

A: `pip-upgrader` will prompt you to confirm each upgrade, allowing you to skip packages that you may want to upgrade later or that have breaking changes.

## Contributing

We welcome contributions to the `pip-upgrader` project! Here's how you can contribute:

1. **Fork the Repository**: Start by forking the `pip-upgrader` repository on GitHub.

2. **Create a New Branch**: Create a new branch for your feature or bug fix:

```bash
git checkout -b your-feature-branch
```

3. **Make Your Changes**: Implement your changes, whether it's adding new features, fixing bugs, or enhancing documentation.

4. **Commit and Push**: Commit your changes with a clear commit message:

```bash
git commit -m "Add detailed documentation for pip-upgrader"
git push origin your-feature-branch
```

5. **Create a Pull Request**: Navigate to your fork on GitHub and submit a pull request to the main repository. Be sure to reference any related issues in your PR description.

6. **Engage in the Review Process**: Be prepared to make changes and respond to feedback from the repository maintainers.

## License

`pip-upgrader` is open-source software licensed under the Apache License Version 2.0. See the [LICENSE](LICENSE) file for more details.