Gimmie

A simple command-line tool to download files from a list of URLs.

Description

Gimmie ("Give me your files") is a lightweight utility that downloads files from a list of web addresses. Simply provide a text file with one URL per line, and Gimmie will handle the rest.

Features

• Downloads files from multiple URLs in sequence
• Extracts filenames automatically from URLs
• Supports any file type available via HTTP/HTTPS
• Handles errors gracefully, continuing to the next file if one fails
• Option to specify a custom download directory

Installation

Requirements

• Python 3.10 or higher
• pip package manager

From PyPI (Recommended)

pip install gimmie

From Source

1. Clone the repository:

   git clone https://github.com/yourusername/gimmie.git
   cd gimmie
   

2. Install the package:

   pip install .
   

Usage

Basic Usage

1. Create a text file (e.g., files-to-download.txt) with one URL per line:

   https://example.com/file1.pdf
   https://example.com/file2.jpg
   https://example.com/file3.zip
   

2. Run Gimmie with the file as an argument:

   gimmie files-to-download.txt
   

3. Files will be downloaded to a downloads directory in your current working directory.

Command-Line Options

gimmie [-h] [-d DIRECTORY] url_file

Arguments:

• url_file: Path to text file containing URLs (one per line)

Options:

• -h, --help: Show help message and exit
• -d DIRECTORY, --directory DIRECTORY: Directory to save downloaded files (default: downloads)

Example

# Download files to a custom directory
gimmie files-to-download.txt -d my_files

URL File Format

The URL file should contain one URL per line. The tool will:

• Strip whitespace from lines
• Skip empty lines and lines starting with '#' (for comments)

Example URL file:

# Files to download
https://example.com/file1.pdf
https://example.com/file2.jpg
https://example.com/file3.zip

Development

Docker Dev Container

The recommended approach is to use a Docker Dev Container as this includes everything you need.

1. Install VSCode
   1. Ensure the ms-vscode-remote.remote-containers extension is installed.
2. Install Docker Desktop
3. Clone the repository
4. Reopen in Container

Setting Up Development Environment

1. Clone the repository

2. Create a virtual environment:

   python -m venv venv
   source venv/bin/activate   # On Linux / MacOS
   venv\Scripts\activate      # On Windows
   

3. Install development dependencies:

   pip install -e ".[dev,test]"
   

Running Tests

Run the tests using PyTest:

pytest

Set the environment variable RUN_INTEGRATION_TESTS=1 to run integration tests that will actually download a file from the internet.

Linux:

export RUN_INTEGRATION_TESTS=1

Windows:

set RUN_INTEGRATION_TESTS=1

Updating Release version number

Rather than set the version explicitly, use Hatch to roll version numbers:

$ hatch version minor
Old: 0.1.0
New: 0.2.0

The final word in the command above controls how the version is incremented:

This ensures that versions are rolled correctly.

Contributing

Contributions are welcome! See CONTRIBUTING.md for how to file issues and submit pull requests. Open a pull request using the provided PR template. CODEOWNERS in .github/CODEOWNERS will be requested for review. This project follows a Code of Conduct. See SECURITY.md for how to report vulnerabilities.

.editorconfig and .vscode/settings.json keep editor formatting consistent (indentation, line endings, trailing whitespace), .gitattributes normalizes line endings and marks binary files, and pre-commit hooks in .pre-commit-config.yaml catch common issues locally before you push (install with pre-commit install).