0
# Requirements Detection
1

2
Automatic discovery and validation of requirements files in the current directory, with support for explicit file specification and recursive inclusion handling.
3

4
## Capabilities
5

6
### Requirements File Discovery
7

8
Discovers and validates requirements files either through auto-detection in the current directory or from explicit file arguments.
9

10
```python { .api }
11
class RequirementsDetector:
12
    def __init__(self, requirements_arg):
13
        """
14
        Initialize requirements detector.
15
        
16
        Args:
17
            requirements_arg (list or None): List of explicit requirements file paths,
18
                                           or None for auto-detection
19
        """
20
    
21
    def get_filenames(self):
22
        """
23
        Returns a list of all detected valid requirements files.
24
        
25
        Returns:
26
            list: List of requirements file paths that were validated
27
        """
28
```
29

30
### Auto-Detection
31

32
Automatically discovers requirements files in the current working directory using common naming patterns.
33

34
```python { .api }
35
def autodetect_files(self):
36
    """
37
    Attempt to detect requirements files in the current working directory.
38
    
39
    Detection patterns:
40
    - requirements.txt in current directory
41
    - requirements.pip in current directory  
42
    - All .txt and .pip files in requirements/ subdirectory
43
    
44
    Also processes recursive inclusions (-r statements).
45
    """
46
```
47

48
### Explicit File Detection
49

50
Validates explicitly provided requirements file paths and processes them for inclusions.
51

52
```python { .api }
53
def detect_files(self, requirements_arg):
54
    """
55
    Validate and process explicitly provided requirements files.
56
    
57
    Args:
58
        requirements_arg (list): List of requirements file paths to validate
59
        
60
    Side effects:
61
        Prints error messages for invalid files
62
        Populates self.filenames with valid files
63
    """
64
```
65

66
### File Validation
67

68
Static method to validate whether a file is a proper requirements file.
69

70
```python { .api }
71
@staticmethod
72
def _is_valid_requirements_file(filename):
73
    """
74
    Check if a file is a valid requirements file.
75
    
76
    Args:
77
        filename (str): Path to file to validate
78
        
79
    Returns:
80
        bool: True if file is valid requirements file
81
        
82
    Validation criteria:
83
    - File extension is .txt or .pip
84
    - File exists and is readable
85
    - MIME type is text/plain or None
86
    """
87
```
88

89
## Recursive Inclusions
90

91
The detector handles recursive `-r` inclusions commonly used in requirements files:
92

93
```python { .api }
94
def _check_inclusions_recursively(self):
95
    """
96
    Check all detected files for -r inclusions and add them recursively.
97
    """
98

99
def _detect_inclusion(self, filename):
100
    """
101
    Detect -r inclusions in a specific requirements file.
102
    
103
    Args:
104
        filename (str): Requirements file to scan for inclusions
105
        
106
    Processing:
107
    - Parses lines starting with '-r '
108
    - Resolves relative paths based on including file's directory
109
    - Recursively processes included files for further inclusions
110
    - Avoids duplicate inclusions
111
    """
112
```
113

114
## Auto-Detection Patterns
115

116
### Current Directory Files
117

118
```
119
requirements.txt      # Primary pattern
120
requirements.pip      # Alternative extension
121
```
122

123
### Requirements Directory
124

125
```
126
requirements/
127
├── base.txt          # Detected
128
├── dev.txt           # Detected  
129
├── production.txt    # Detected
130
├── test.pip          # Detected
131
└── README.md         # Ignored (wrong extension)
132
```
133

134
### Recursive Inclusions
135

136
Requirements files can include other files using `-r` statements:
137

138
```
139
# requirements/base.txt
140
django==3.2.0
141
requests==2.25.1
142

143
# requirements/dev.txt  
144
-r base.txt
145
pytest==6.2.4
146
black==21.5.4
147

148
# requirements/production.txt
149
-r base.txt
150
gunicorn==20.1.0
151
```
152

153
When `requirements/dev.txt` is detected, the detector will automatically include `requirements/base.txt` as well.
154

155
## Usage Examples
156

157
### Auto-Detection
158

159
```python
160
from pip_upgrader.requirements_detector import RequirementsDetector
161

162
# Auto-detect requirements files in current directory
163
detector = RequirementsDetector(None)
164
filenames = detector.get_filenames()
165
print(filenames)  # ['requirements.txt', 'requirements/dev.txt', ...]
166
```
167

168
### Explicit Files
169

170
```python
171
from pip_upgrader.requirements_detector import RequirementsDetector
172

173
# Specify explicit requirements files
174
files = ['requirements.txt', 'requirements/production.txt']
175
detector = RequirementsDetector(files)
176
filenames = detector.get_filenames()
177
print(filenames)  # Includes any -r inclusions found
178
```
179

180
### File Validation
181

182
```python
183
from pip_upgrader.requirements_detector import RequirementsDetector
184

185
# Check if a file is a valid requirements file
186
is_valid = RequirementsDetector._is_valid_requirements_file('requirements.txt')
187
print(is_valid)  # True if valid
188
```
189

190
## Error Handling
191

192
- **Invalid files**: Prints error message "Invalid requirements file: {filename}" for files that fail validation
193
- **Missing inclusions**: Silently skips `-r` inclusions that point to non-existent files
194
- **Circular inclusions**: Prevents infinite loops by checking for duplicates before adding files
195
- **Permission errors**: File reading errors are handled gracefully during validation
196

197
## File Format Support
198

199
### Supported Extensions
200
- `.txt` files
201
- `.pip` files
202

203
### Supported Content
204
- Standard pip requirements format
205
- Comments (lines starting with #)
206
- Recursive inclusions (-r filename)
207
- Package extras (package[extra1,extra2]==1.0.0)
208
- Various pip options (filtered out during parsing)
209

210
### Unsupported Content
211
- Binary files
212
- Files with unsupported MIME types
213
- Directory paths (only files are accepted)