docs: add virtual environment and pipx installation notes

- Add recommendation to install within virtual environment
- Include pipx installation option for global use
- Improve installation section organization

README.md

@@ -14,11 +14,19 @@ Compatible with Python 3.11, 3.12, and 3.13.
 - Clean, informative output with version information
 - Preserves requirements.txt comments and formatting
 - Creates requirements.txt if it doesn't exist
+- Support for custom requirements file paths
+- Smart detection of multiple requirements files
 - Full support for Python 3.11, 3.12, and 3.13
 
 ## Installation
 
+It's recommended to install pip-add within a virtual environment to avoid conflicts with system packages:
+
 ```bash
+# Create and activate virtual environment
+python -m venv venv
+source venv/bin/activate  # or `venv\Scripts\activate` on Windows
+
 # Install from PyPI
 pip install pip-add
 
@@ -26,6 +34,13 @@ pip install pip-add
 pip install --upgrade pip-add
 ```
 
+For global installation (use with caution), you can install with pipx:
+
+```bash
+# Install globally using pipx
+pipx install pip-add
+```
+
 ## Usage
 
 ### Installation
@@ -53,6 +68,34 @@ pip-add -d requests
 #   - requests (2.32.3)
 #   - urllib3 (2.2.3)
 # ✓ Updated requirements.txt
+
+# Install using custom requirements file
+pip-add -f requirements/dev.txt requests
+# Output:
+# Installing requests...
+# ✓ Successfully installed requests (2.32.3)
+# ✓ Updated requirements/dev.txt
+```
+
+### Multiple Requirements Files
+
+When multiple requirements files are found in your project:
+
+```bash
+# Tool will show available files:
+pip-add requests
+# Output:
+# ℹ️  Found multiple requirements files:
+#   - requirements.txt
+#   - requirements/dev.txt
+#   - requirements/prod.txt
+#
+# Using: requirements.txt
+# To use a specific file, run the command with -f/--requirements-file option:
+# Example: pip-add -f requirements/dev.txt requests
+
+# Specify which file to use:
+pip-add -f requirements/dev.txt requests
 ```
 
 ### Removal
@@ -79,12 +122,19 @@ pip-add -d -r requests
 #   - idna (needed by: email-validator, cryptography)
 #
 # ✓ Updated requirements.txt
+
+# Remove from specific requirements file
+pip-add -r -f requirements/dev.txt requests
+# Output:
+# Removing packages...
+# ✓ Successfully uninstalled requests (2.32.3)
+# ✓ Updated requirements/dev.txt
 ```
 
 ## Command Line Options
 
 ```
-pip-add [-h] [-d] [-e] [-r] package
+pip-add [-h] [-d] [-e] [-r] [-f REQUIREMENTS_FILE] package
 
 positional arguments:
   package               Package to install or remove
@@ -94,6 +144,8 @@ options:
   -d, --dependencies   Include dependencies when installing or removing
   -e, --exact         Use == instead of >= for version specification
   -r, --remove        Remove package(s) and their entries from requirements.txt
+  -f, --requirements-file
+                      Path to custom requirements.txt file
 ```
 
 ## How It Works
@@ -103,7 +155,7 @@ options:
 1. Installs the specified package using pip
 2. Retrieves installed version information
 3. With `-d`: tracks and installs all dependencies
-4. Updates requirements.txt with new package(s)
+4. Updates requirements.txt (or specified requirements file) with new package(s)
 5. Uses `>=` by default or `==` with `-e` flag
 
 ### Removal Process
@@ -112,9 +164,21 @@ options:
 2. Identifies which dependencies are safe to remove
 3. Checks if any dependencies are needed by other packages
 4. Safely removes unused packages
-5. Updates requirements.txt
+5. Updates requirements.txt (or specified requirements file)
 6. Reports kept dependencies and their dependents
 
+### Requirements File Handling
+
+1. By default, looks for requirements.txt in the current directory
+2. Creates requirements.txt if it doesn't exist
+3. With `-f`: uses specified requirements file path
+4. Creates directories if needed for custom file paths
+5. Preserves comments and formatting in existing files
+6. When multiple files are found:
+   - Lists all available requirements files
+   - Shows which file will be used by default
+   - Provides example command to specify a particular file
+
 ## Safe Dependency Handling
 
 The tool is designed to safely handle dependencies:
@@ -155,6 +219,11 @@ pip install -e .
 # First time setup
 pip-add -d flask
 # Creates requirements.txt and adds Flask with dependencies
+
+# Multiple requirements files
+pip-add -f requirements/dev.txt pytest
+pip-add -f requirements/prod.txt gunicorn
+# Manages separate requirement files for different environments
 ```
 
 ### Updating Dependencies
@@ -178,6 +247,7 @@ pip-add -d -r flask
 1. **Package not found in requirements.txt**
    - The file will be created automatically
    - Existing comments are preserved
+   - Use `-f` to specify a different requirements file
 
 2. **Dependency conflicts**
    - Uses `>=` by default to minimize conflicts
@@ -186,3 +256,9 @@ pip-add -d -r flask
 3. **Dependencies not removing**
    - Check the output for dependencies kept
    - Tool will show which packages need them
+
+4. **Multiple requirements files**
+   - Tool will list all available requirements files
+   - Shows which file will be used by default
+   - Provides example command to specify a particular file
+   - Use `-f` to specify which file to use

pip_add/cli.py

@@ -4,14 +4,27 @@ import subprocess
 import pkg_resources
 import argparse
 from pkg_resources import working_set
+from .utils import find_requirements as utils_find_requirements
 
-def find_requirements():
+def find_requirements(custom_path=None):
-    """Find requirements.txt in current directory or create it"""
+    """Find requirements.txt using utils or use custom path"""
-    req_file = 'requirements.txt'
+    if custom_path:
+        # If custom path provided, ensure directory exists
+        os.makedirs(os.path.dirname(os.path.abspath(custom_path)), exist_ok=True)
+        if not os.path.exists(custom_path):
+            with open(custom_path, 'w') as f:
+                f.write('# Python dependencies\n')
+        return custom_path
     
-    if not os.path.exists(req_file):
+    # Use utils.find_requirements() to search for requirements files
-        with open(req_file, 'w') as f:
+    req_file, found_files = utils_find_requirements()
-            f.write('# Python dependencies\n')
+    if len(found_files) > 1:
+        print("\nℹ️  Found multiple requirements files:")
+        for f in found_files:
+            print(f"  - {f}")
+        print(f"\nUsing: {req_file}")
+        print("To use a specific file, run the command with -f/--requirements-file option:")
+        print(f"Example: pip-add -f {found_files[0]} <package>")
     
     return req_file
 
@@ -168,10 +181,12 @@ def main():
                       help='Use == instead of >= for version specification')
     parser.add_argument('-r', '--remove', action='store_true',
                       help='Remove package(s) and their entries from requirements.txt')
+    parser.add_argument('-f', '--requirements-file',
+                      help='Path to custom requirements.txt file')
     
     args = parser.parse_args()
     package = args.package
-    req_file = find_requirements()
+    req_file = find_requirements(args.requirements_file)
     
     try:
         if args.remove:
@@ -235,4 +250,4 @@ def main():
         sys.exit(1)
 
 if __name__ == '__main__':
-    main()
+    main()

setup.py

@@ -2,7 +2,7 @@ from setuptools import setup, find_packages
 
 setup(
     name="pip-add",
-    version="0.1.2",
+    version="0.2.4",
     packages=find_packages(),
     install_requires=[
         "pip",
@@ -21,13 +21,23 @@ setup(
     url="https://github.com/PacNPal/pip-add",
     classifiers=[
         "Development Status :: 4 - Beta",
+        "Environment :: Console",
         "Intended Audience :: Developers",
+        "Intended Audience :: Information Technology",
+        "Intended Audience :: System Administrators",
         "License :: OSI Approved :: MIT License",
+        "Natural Language :: English",
+        "Operating System :: OS Independent",
         "Programming Language :: Python :: 3",
         "Programming Language :: Python :: 3.11",
         "Programming Language :: Python :: 3.12",
         "Programming Language :: Python :: 3.13",
+        "Programming Language :: Python :: Implementation :: CPython",
         "Topic :: Software Development :: Libraries :: Python Modules",
+        "Topic :: System :: Installation/Setup",
+        "Topic :: System :: Software Distribution",
+        "Topic :: System :: Systems Administration",
+        "Topic :: Utilities",
     ],
     python_requires=">=3.11",
 )