unified-file-reader 0.1.1__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- unified_file_reader-0.1.1/LICENSE +21 -0
- unified_file_reader-0.1.1/MANIFEST.in +5 -0
- unified_file_reader-0.1.1/PKG-INFO +331 -0
- unified_file_reader-0.1.1/README.md +297 -0
- unified_file_reader-0.1.1/pyproject.toml +68 -0
- unified_file_reader-0.1.1/requirements.txt +35 -0
- unified_file_reader-0.1.1/setup.cfg +4 -0
- unified_file_reader-0.1.1/setup.py +14 -0
- unified_file_reader-0.1.1/tests/__init__.py +1 -0
- unified_file_reader-0.1.1/tests/conftest.py +109 -0
- unified_file_reader-0.1.1/tests/test_api.py +102 -0
- unified_file_reader-0.1.1/tests/test_csv_reader.py +81 -0
- unified_file_reader-0.1.1/tests/test_docx_reader.py +99 -0
- unified_file_reader-0.1.1/tests/test_excel_reader.py +94 -0
- unified_file_reader-0.1.1/tests/test_file_utils.py +120 -0
- unified_file_reader-0.1.1/tests/test_json_reader.py +90 -0
- unified_file_reader-0.1.1/tests/test_pdf_reader.py +78 -0
- unified_file_reader-0.1.1/tests/test_registry.py +123 -0
- unified_file_reader-0.1.1/tests/test_txt_reader.py +97 -0
- unified_file_reader-0.1.1/unified_file_reader/__init__.py +13 -0
- unified_file_reader-0.1.1/unified_file_reader/api.py +80 -0
- unified_file_reader-0.1.1/unified_file_reader/config/__init__.py +1 -0
- unified_file_reader-0.1.1/unified_file_reader/config/supported_formats.py +65 -0
- unified_file_reader-0.1.1/unified_file_reader/exceptions.py +24 -0
- unified_file_reader-0.1.1/unified_file_reader/interfaces/__init__.py +1 -0
- unified_file_reader-0.1.1/unified_file_reader/interfaces/base_reader.py +48 -0
- unified_file_reader-0.1.1/unified_file_reader/readers/__init__.py +1 -0
- unified_file_reader-0.1.1/unified_file_reader/readers/csv_reader.py +48 -0
- unified_file_reader-0.1.1/unified_file_reader/readers/docx_reader.py +44 -0
- unified_file_reader-0.1.1/unified_file_reader/readers/excel_reader.py +47 -0
- unified_file_reader-0.1.1/unified_file_reader/readers/json_reader.py +41 -0
- unified_file_reader-0.1.1/unified_file_reader/readers/pdf_reader.py +50 -0
- unified_file_reader-0.1.1/unified_file_reader/readers/txt_reader.py +43 -0
- unified_file_reader-0.1.1/unified_file_reader/registry.py +78 -0
- unified_file_reader-0.1.1/unified_file_reader/utils/__init__.py +1 -0
- unified_file_reader-0.1.1/unified_file_reader/utils/file_utils.py +84 -0
- unified_file_reader-0.1.1/unified_file_reader.egg-info/PKG-INFO +331 -0
- unified_file_reader-0.1.1/unified_file_reader.egg-info/SOURCES.txt +39 -0
- unified_file_reader-0.1.1/unified_file_reader.egg-info/dependency_links.txt +1 -0
- unified_file_reader-0.1.1/unified_file_reader.egg-info/requires.txt +12 -0
- unified_file_reader-0.1.1/unified_file_reader.egg-info/top_level.txt +1 -0
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2024 Unified File Reader Contributors
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,331 @@
|
|
|
1
|
+
Metadata-Version: 2.1
|
|
2
|
+
Name: unified-file-reader
|
|
3
|
+
Version: 0.1.1
|
|
4
|
+
Summary: A clean, extensible file reader library supporting CSV, JSON, TXT, XLSX, PDF, and DOCX formats. Developed and tested on Python 3.12.8 (recommended). Other versions within 3.9–3.12 should also work.
|
|
5
|
+
Author-email: Praveenkumar B <bpraveenkumark1@gmail.com>
|
|
6
|
+
License: MIT
|
|
7
|
+
Project-URL: Homepage, https://github.com/praveen9392/unified-file-reader
|
|
8
|
+
Project-URL: Documentation, https://github.com/praveen9392/unified-file-reader#readme
|
|
9
|
+
Project-URL: Repository, https://github.com/praveen9392/unified-file-reader.git
|
|
10
|
+
Keywords: file-reader,csv,json,pdf,docx,xlsx,clean-architecture
|
|
11
|
+
Classifier: Development Status :: 3 - Alpha
|
|
12
|
+
Classifier: Intended Audience :: Developers
|
|
13
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
14
|
+
Classifier: Programming Language :: Python :: 3
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.9
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
19
|
+
Classifier: Topic :: Software Development :: Libraries :: Python Modules
|
|
20
|
+
Requires-Python: >=3.9
|
|
21
|
+
Description-Content-Type: text/markdown
|
|
22
|
+
License-File: LICENSE
|
|
23
|
+
Requires-Dist: pandas>=1.5.0
|
|
24
|
+
Requires-Dist: openpyxl>=3.0.0
|
|
25
|
+
Requires-Dist: pypdf>=3.0.0
|
|
26
|
+
Requires-Dist: python-docx>=0.8.11
|
|
27
|
+
Provides-Extra: dev
|
|
28
|
+
Requires-Dist: pytest>=7.0.0; extra == "dev"
|
|
29
|
+
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
|
|
30
|
+
Requires-Dist: black>=23.0.0; extra == "dev"
|
|
31
|
+
Requires-Dist: flake8>=6.0.0; extra == "dev"
|
|
32
|
+
Requires-Dist: mypy>=1.0.0; extra == "dev"
|
|
33
|
+
Requires-Dist: isort>=5.12.0; extra == "dev"
|
|
34
|
+
|
|
35
|
+
# Unified File Reader
|
|
36
|
+
|
|
37
|
+
A clean, extensible Python library for reading multiple file formats with a unified API. Built following Clean Code and Clean Architecture principles.
|
|
38
|
+
|
|
39
|
+
## Features
|
|
40
|
+
|
|
41
|
+
- **Unified API**: Single `read_file()` function for all supported formats
|
|
42
|
+
- **Multiple Formats**: CSV, JSON, TXT, XLSX, PDF, DOCX
|
|
43
|
+
- **Clean Architecture**: Modular, testable, and maintainable codebase
|
|
44
|
+
- **Extensible**: Add new file readers without modifying core logic
|
|
45
|
+
- **Type-Safe**: Full type hints for better IDE support
|
|
46
|
+
- **Well-Tested**: Comprehensive test suite with high coverage
|
|
47
|
+
- **Production-Ready**: PyPI packaging, logging, and error handling
|
|
48
|
+
|
|
49
|
+
## Requirements
|
|
50
|
+
|
|
51
|
+
Developed and tested on **Python 3.12.8** (recommended). Other versions within **3.9–3.12** should also work.
|
|
52
|
+
|
|
53
|
+
- pip (latest version recommended)
|
|
54
|
+
- Virtual environment tool (`python -m venv`)
|
|
55
|
+
|
|
56
|
+
See `requirements.txt` for the exact dependency versions used with Python 3.12.8.
|
|
57
|
+
|
|
58
|
+
## Installation
|
|
59
|
+
|
|
60
|
+
### From PyPI
|
|
61
|
+
|
|
62
|
+
```bash
|
|
63
|
+
pip install unified-file-reader
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
### From source (development setup)
|
|
67
|
+
|
|
68
|
+
```bash
|
|
69
|
+
# Clone the repository
|
|
70
|
+
git clone https://github.com/praveen9392/unified-file-reader.git
|
|
71
|
+
cd unified-file-reader
|
|
72
|
+
|
|
73
|
+
# Create a virtual environment (recommended)
|
|
74
|
+
python -m venv .venv
|
|
75
|
+
|
|
76
|
+
# Activate
|
|
77
|
+
# Windows (PowerShell)
|
|
78
|
+
.venv\Scripts\Activate.ps1
|
|
79
|
+
# Windows (cmd)
|
|
80
|
+
.venv\Scripts\activate.bat
|
|
81
|
+
# macOS / Linux
|
|
82
|
+
source .venv/bin/activate
|
|
83
|
+
|
|
84
|
+
# Install runtime + dev dependencies
|
|
85
|
+
pip install -e ".[dev]"
|
|
86
|
+
|
|
87
|
+
# Alternatively, to match exact versions from this repo
|
|
88
|
+
pip install -r requirements.txt
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
## Quick Start
|
|
92
|
+
|
|
93
|
+
```python
|
|
94
|
+
from unified_file_reader import read_file
|
|
95
|
+
|
|
96
|
+
# Read any supported file format
|
|
97
|
+
data = read_file("data.csv")
|
|
98
|
+
data = read_file("config.json")
|
|
99
|
+
data = read_file("document.pdf")
|
|
100
|
+
data = read_file("spreadsheet.xlsx")
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
## Supported Formats
|
|
104
|
+
|
|
105
|
+
| Format | Extension | Return Type | Notes |
|
|
106
|
+
|--------|-----------|-------------|-------|
|
|
107
|
+
| CSV | `.csv` | `List[Dict]` | Returns list of dictionaries |
|
|
108
|
+
| JSON | `.json` | `Any` | Preserves JSON structure |
|
|
109
|
+
| TXT | `.txt` | `str` | Returns plain text content |
|
|
110
|
+
| Excel | `.xlsx` | `List[Dict]` | Returns list of dictionaries |
|
|
111
|
+
| PDF | `.pdf` | `str` | Extracts all text content |
|
|
112
|
+
| DOCX | `.docx` | `str` | Extracts all paragraph text |
|
|
113
|
+
|
|
114
|
+
## Architecture Overview
|
|
115
|
+
|
|
116
|
+
```
|
|
117
|
+
unified_file_reader/
|
|
118
|
+
├── api.py # Public API entry point
|
|
119
|
+
├── registry.py # Reader registry (dependency inversion)
|
|
120
|
+
├── exceptions.py # Custom exceptions
|
|
121
|
+
├── interfaces/
|
|
122
|
+
│ └── base_reader.py # Abstract reader contract
|
|
123
|
+
├── readers/ # Concrete implementations
|
|
124
|
+
│ ├── csv_reader.py
|
|
125
|
+
│ ├── json_reader.py
|
|
126
|
+
│ ├── txt_reader.py
|
|
127
|
+
│ ├── excel_reader.py
|
|
128
|
+
│ ├── pdf_reader.py
|
|
129
|
+
│ └── docx_reader.py
|
|
130
|
+
├── utils/
|
|
131
|
+
│ └── file_utils.py # Utility functions
|
|
132
|
+
└── config/
|
|
133
|
+
└── supported_formats.py
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
### Design Principles
|
|
137
|
+
|
|
138
|
+
- **Single Responsibility Principle (SRP)**: Each reader handles one format
|
|
139
|
+
- **Open/Closed Principle (OCP)**: Add new readers without modifying existing code
|
|
140
|
+
- **Liskov Substitution Principle (LSP)**: All readers implement the same interface
|
|
141
|
+
- **Interface Segregation Principle (ISP)**: Minimal, focused interfaces
|
|
142
|
+
- **Dependency Inversion Principle (DIP)**: High-level modules depend on abstractions
|
|
143
|
+
|
|
144
|
+
## Usage Examples
|
|
145
|
+
|
|
146
|
+
### Reading CSV Files
|
|
147
|
+
|
|
148
|
+
```python
|
|
149
|
+
from unified_file_reader import read_file
|
|
150
|
+
|
|
151
|
+
data = read_file("employees.csv")
|
|
152
|
+
# Returns: [{"name": "John", "age": "30"}, {"name": "Jane", "age": "28"}]
|
|
153
|
+
|
|
154
|
+
for row in data:
|
|
155
|
+
print(f"{row['name']}: {row['age']}")
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
### Reading JSON Files
|
|
159
|
+
|
|
160
|
+
```python
|
|
161
|
+
config = read_file("config.json")
|
|
162
|
+
# Returns: {"database": {"host": "localhost", "port": 5432}}
|
|
163
|
+
|
|
164
|
+
print(config["database"]["host"])
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
### Reading Text Files
|
|
168
|
+
|
|
169
|
+
```python
|
|
170
|
+
content = read_file("document.txt")
|
|
171
|
+
# Returns: "This is the file content..."
|
|
172
|
+
|
|
173
|
+
print(content)
|
|
174
|
+
```
|
|
175
|
+
|
|
176
|
+
### Reading Excel Files
|
|
177
|
+
|
|
178
|
+
```python
|
|
179
|
+
data = read_file("report.xlsx")
|
|
180
|
+
# Returns: [{"Quarter": "Q1", "Revenue": 100000}, ...]
|
|
181
|
+
|
|
182
|
+
for row in data:
|
|
183
|
+
print(f"{row['Quarter']}: ${row['Revenue']}")
|
|
184
|
+
```
|
|
185
|
+
|
|
186
|
+
### Reading PDF Files
|
|
187
|
+
|
|
188
|
+
```python
|
|
189
|
+
text = read_file("document.pdf")
|
|
190
|
+
# Returns: "Page 1 content...\nPage 2 content..."
|
|
191
|
+
|
|
192
|
+
print(text)
|
|
193
|
+
```
|
|
194
|
+
|
|
195
|
+
### Reading DOCX Files
|
|
196
|
+
|
|
197
|
+
```python
|
|
198
|
+
text = read_file("report.docx")
|
|
199
|
+
# Returns: "Paragraph 1...\nParagraph 2..."
|
|
200
|
+
|
|
201
|
+
print(text)
|
|
202
|
+
```
|
|
203
|
+
|
|
204
|
+
## Error Handling
|
|
205
|
+
|
|
206
|
+
```python
|
|
207
|
+
from unified_file_reader import read_file
|
|
208
|
+
from unified_file_reader.exceptions import UnsupportedFormatError, ReaderError
|
|
209
|
+
|
|
210
|
+
try:
|
|
211
|
+
data = read_file("file.xyz")
|
|
212
|
+
except UnsupportedFormatError as e:
|
|
213
|
+
print(f"Format not supported: {e}")
|
|
214
|
+
except FileNotFoundError as e:
|
|
215
|
+
print(f"File not found: {e}")
|
|
216
|
+
except ReaderError as e:
|
|
217
|
+
print(f"Reading error: {e}")
|
|
218
|
+
```
|
|
219
|
+
|
|
220
|
+
## Extending with New Readers
|
|
221
|
+
|
|
222
|
+
To add support for a new file format:
|
|
223
|
+
|
|
224
|
+
1. Create a new reader class in `unified_file_reader/readers/`:
|
|
225
|
+
|
|
226
|
+
```python
|
|
227
|
+
from unified_file_reader.interfaces.base_reader import BaseReader
|
|
228
|
+
from unified_file_reader.utils.file_utils import ensure_file_exists
|
|
229
|
+
|
|
230
|
+
class YAMLReader(BaseReader):
|
|
231
|
+
supported_extensions = [".yaml", ".yml"]
|
|
232
|
+
|
|
233
|
+
def can_read(self, extension: str) -> bool:
|
|
234
|
+
return extension in self.supported_extensions
|
|
235
|
+
|
|
236
|
+
def read(self, path: str):
|
|
237
|
+
ensure_file_exists(path)
|
|
238
|
+
import yaml
|
|
239
|
+
with open(path, 'r', encoding='utf-8') as f:
|
|
240
|
+
return yaml.safe_load(f)
|
|
241
|
+
```
|
|
242
|
+
|
|
243
|
+
2. Register it in `unified_file_reader/registry.py`:
|
|
244
|
+
|
|
245
|
+
```python
|
|
246
|
+
from unified_file_reader.readers.yaml_reader import YAMLReader
|
|
247
|
+
|
|
248
|
+
readers = [
|
|
249
|
+
# ... existing readers ...
|
|
250
|
+
YAMLReader(),
|
|
251
|
+
]
|
|
252
|
+
```
|
|
253
|
+
|
|
254
|
+
3. Add tests in `tests/test_yaml_reader.py`
|
|
255
|
+
|
|
256
|
+
4. Update `supported_formats.py` with metadata
|
|
257
|
+
|
|
258
|
+
That's it! No changes needed to the core API.
|
|
259
|
+
|
|
260
|
+
## Testing
|
|
261
|
+
|
|
262
|
+
Run the test suite:
|
|
263
|
+
|
|
264
|
+
```bash
|
|
265
|
+
pytest
|
|
266
|
+
```
|
|
267
|
+
|
|
268
|
+
With coverage:
|
|
269
|
+
|
|
270
|
+
```bash
|
|
271
|
+
pytest --cov=unified_file_reader
|
|
272
|
+
```
|
|
273
|
+
|
|
274
|
+
Run specific tests:
|
|
275
|
+
|
|
276
|
+
```bash
|
|
277
|
+
pytest tests/test_api.py -v
|
|
278
|
+
```
|
|
279
|
+
|
|
280
|
+
## Development
|
|
281
|
+
|
|
282
|
+
Install development dependencies:
|
|
283
|
+
|
|
284
|
+
```bash
|
|
285
|
+
pip install -e ".[dev]"
|
|
286
|
+
```
|
|
287
|
+
|
|
288
|
+
Format code:
|
|
289
|
+
|
|
290
|
+
```bash
|
|
291
|
+
black unified_file_reader tests
|
|
292
|
+
isort unified_file_reader tests
|
|
293
|
+
```
|
|
294
|
+
|
|
295
|
+
Type checking:
|
|
296
|
+
|
|
297
|
+
```bash
|
|
298
|
+
mypy unified_file_reader
|
|
299
|
+
```
|
|
300
|
+
|
|
301
|
+
Linting:
|
|
302
|
+
|
|
303
|
+
```bash
|
|
304
|
+
flake8 unified_file_reader tests
|
|
305
|
+
```
|
|
306
|
+
|
|
307
|
+
## Contributing
|
|
308
|
+
|
|
309
|
+
Contributions are welcome! Please:
|
|
310
|
+
|
|
311
|
+
1. Fork the repository
|
|
312
|
+
2. Create a feature branch
|
|
313
|
+
3. Add tests for new functionality
|
|
314
|
+
4. Ensure all tests pass
|
|
315
|
+
5. Submit a pull request
|
|
316
|
+
|
|
317
|
+
## License
|
|
318
|
+
|
|
319
|
+
MIT License - see LICENSE file for details
|
|
320
|
+
|
|
321
|
+
## Changelog
|
|
322
|
+
|
|
323
|
+
### v0.1.0 (Initial Release)
|
|
324
|
+
- Initial release with support for CSV, JSON, TXT, XLSX, PDF, DOCX
|
|
325
|
+
- Clean Architecture implementation
|
|
326
|
+
- Full test coverage
|
|
327
|
+
- PyPI packaging
|
|
328
|
+
|
|
329
|
+
## Support
|
|
330
|
+
|
|
331
|
+
For issues, questions, or suggestions, please open an issue on GitHub.
|
|
@@ -0,0 +1,297 @@
|
|
|
1
|
+
# Unified File Reader
|
|
2
|
+
|
|
3
|
+
A clean, extensible Python library for reading multiple file formats with a unified API. Built following Clean Code and Clean Architecture principles.
|
|
4
|
+
|
|
5
|
+
## Features
|
|
6
|
+
|
|
7
|
+
- **Unified API**: Single `read_file()` function for all supported formats
|
|
8
|
+
- **Multiple Formats**: CSV, JSON, TXT, XLSX, PDF, DOCX
|
|
9
|
+
- **Clean Architecture**: Modular, testable, and maintainable codebase
|
|
10
|
+
- **Extensible**: Add new file readers without modifying core logic
|
|
11
|
+
- **Type-Safe**: Full type hints for better IDE support
|
|
12
|
+
- **Well-Tested**: Comprehensive test suite with high coverage
|
|
13
|
+
- **Production-Ready**: PyPI packaging, logging, and error handling
|
|
14
|
+
|
|
15
|
+
## Requirements
|
|
16
|
+
|
|
17
|
+
Developed and tested on **Python 3.12.8** (recommended). Other versions within **3.9–3.12** should also work.
|
|
18
|
+
|
|
19
|
+
- pip (latest version recommended)
|
|
20
|
+
- Virtual environment tool (`python -m venv`)
|
|
21
|
+
|
|
22
|
+
See `requirements.txt` for the exact dependency versions used with Python 3.12.8.
|
|
23
|
+
|
|
24
|
+
## Installation
|
|
25
|
+
|
|
26
|
+
### From PyPI
|
|
27
|
+
|
|
28
|
+
```bash
|
|
29
|
+
pip install unified-file-reader
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
### From source (development setup)
|
|
33
|
+
|
|
34
|
+
```bash
|
|
35
|
+
# Clone the repository
|
|
36
|
+
git clone https://github.com/praveen9392/unified-file-reader.git
|
|
37
|
+
cd unified-file-reader
|
|
38
|
+
|
|
39
|
+
# Create a virtual environment (recommended)
|
|
40
|
+
python -m venv .venv
|
|
41
|
+
|
|
42
|
+
# Activate
|
|
43
|
+
# Windows (PowerShell)
|
|
44
|
+
.venv\Scripts\Activate.ps1
|
|
45
|
+
# Windows (cmd)
|
|
46
|
+
.venv\Scripts\activate.bat
|
|
47
|
+
# macOS / Linux
|
|
48
|
+
source .venv/bin/activate
|
|
49
|
+
|
|
50
|
+
# Install runtime + dev dependencies
|
|
51
|
+
pip install -e ".[dev]"
|
|
52
|
+
|
|
53
|
+
# Alternatively, to match exact versions from this repo
|
|
54
|
+
pip install -r requirements.txt
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
## Quick Start
|
|
58
|
+
|
|
59
|
+
```python
|
|
60
|
+
from unified_file_reader import read_file
|
|
61
|
+
|
|
62
|
+
# Read any supported file format
|
|
63
|
+
data = read_file("data.csv")
|
|
64
|
+
data = read_file("config.json")
|
|
65
|
+
data = read_file("document.pdf")
|
|
66
|
+
data = read_file("spreadsheet.xlsx")
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
## Supported Formats
|
|
70
|
+
|
|
71
|
+
| Format | Extension | Return Type | Notes |
|
|
72
|
+
|--------|-----------|-------------|-------|
|
|
73
|
+
| CSV | `.csv` | `List[Dict]` | Returns list of dictionaries |
|
|
74
|
+
| JSON | `.json` | `Any` | Preserves JSON structure |
|
|
75
|
+
| TXT | `.txt` | `str` | Returns plain text content |
|
|
76
|
+
| Excel | `.xlsx` | `List[Dict]` | Returns list of dictionaries |
|
|
77
|
+
| PDF | `.pdf` | `str` | Extracts all text content |
|
|
78
|
+
| DOCX | `.docx` | `str` | Extracts all paragraph text |
|
|
79
|
+
|
|
80
|
+
## Architecture Overview
|
|
81
|
+
|
|
82
|
+
```
|
|
83
|
+
unified_file_reader/
|
|
84
|
+
├── api.py # Public API entry point
|
|
85
|
+
├── registry.py # Reader registry (dependency inversion)
|
|
86
|
+
├── exceptions.py # Custom exceptions
|
|
87
|
+
├── interfaces/
|
|
88
|
+
│ └── base_reader.py # Abstract reader contract
|
|
89
|
+
├── readers/ # Concrete implementations
|
|
90
|
+
│ ├── csv_reader.py
|
|
91
|
+
│ ├── json_reader.py
|
|
92
|
+
│ ├── txt_reader.py
|
|
93
|
+
│ ├── excel_reader.py
|
|
94
|
+
│ ├── pdf_reader.py
|
|
95
|
+
│ └── docx_reader.py
|
|
96
|
+
├── utils/
|
|
97
|
+
│ └── file_utils.py # Utility functions
|
|
98
|
+
└── config/
|
|
99
|
+
└── supported_formats.py
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
### Design Principles
|
|
103
|
+
|
|
104
|
+
- **Single Responsibility Principle (SRP)**: Each reader handles one format
|
|
105
|
+
- **Open/Closed Principle (OCP)**: Add new readers without modifying existing code
|
|
106
|
+
- **Liskov Substitution Principle (LSP)**: All readers implement the same interface
|
|
107
|
+
- **Interface Segregation Principle (ISP)**: Minimal, focused interfaces
|
|
108
|
+
- **Dependency Inversion Principle (DIP)**: High-level modules depend on abstractions
|
|
109
|
+
|
|
110
|
+
## Usage Examples
|
|
111
|
+
|
|
112
|
+
### Reading CSV Files
|
|
113
|
+
|
|
114
|
+
```python
|
|
115
|
+
from unified_file_reader import read_file
|
|
116
|
+
|
|
117
|
+
data = read_file("employees.csv")
|
|
118
|
+
# Returns: [{"name": "John", "age": "30"}, {"name": "Jane", "age": "28"}]
|
|
119
|
+
|
|
120
|
+
for row in data:
|
|
121
|
+
print(f"{row['name']}: {row['age']}")
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
### Reading JSON Files
|
|
125
|
+
|
|
126
|
+
```python
|
|
127
|
+
config = read_file("config.json")
|
|
128
|
+
# Returns: {"database": {"host": "localhost", "port": 5432}}
|
|
129
|
+
|
|
130
|
+
print(config["database"]["host"])
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
### Reading Text Files
|
|
134
|
+
|
|
135
|
+
```python
|
|
136
|
+
content = read_file("document.txt")
|
|
137
|
+
# Returns: "This is the file content..."
|
|
138
|
+
|
|
139
|
+
print(content)
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
### Reading Excel Files
|
|
143
|
+
|
|
144
|
+
```python
|
|
145
|
+
data = read_file("report.xlsx")
|
|
146
|
+
# Returns: [{"Quarter": "Q1", "Revenue": 100000}, ...]
|
|
147
|
+
|
|
148
|
+
for row in data:
|
|
149
|
+
print(f"{row['Quarter']}: ${row['Revenue']}")
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
### Reading PDF Files
|
|
153
|
+
|
|
154
|
+
```python
|
|
155
|
+
text = read_file("document.pdf")
|
|
156
|
+
# Returns: "Page 1 content...\nPage 2 content..."
|
|
157
|
+
|
|
158
|
+
print(text)
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
### Reading DOCX Files
|
|
162
|
+
|
|
163
|
+
```python
|
|
164
|
+
text = read_file("report.docx")
|
|
165
|
+
# Returns: "Paragraph 1...\nParagraph 2..."
|
|
166
|
+
|
|
167
|
+
print(text)
|
|
168
|
+
```
|
|
169
|
+
|
|
170
|
+
## Error Handling
|
|
171
|
+
|
|
172
|
+
```python
|
|
173
|
+
from unified_file_reader import read_file
|
|
174
|
+
from unified_file_reader.exceptions import UnsupportedFormatError, ReaderError
|
|
175
|
+
|
|
176
|
+
try:
|
|
177
|
+
data = read_file("file.xyz")
|
|
178
|
+
except UnsupportedFormatError as e:
|
|
179
|
+
print(f"Format not supported: {e}")
|
|
180
|
+
except FileNotFoundError as e:
|
|
181
|
+
print(f"File not found: {e}")
|
|
182
|
+
except ReaderError as e:
|
|
183
|
+
print(f"Reading error: {e}")
|
|
184
|
+
```
|
|
185
|
+
|
|
186
|
+
## Extending with New Readers
|
|
187
|
+
|
|
188
|
+
To add support for a new file format:
|
|
189
|
+
|
|
190
|
+
1. Create a new reader class in `unified_file_reader/readers/`:
|
|
191
|
+
|
|
192
|
+
```python
|
|
193
|
+
from unified_file_reader.interfaces.base_reader import BaseReader
|
|
194
|
+
from unified_file_reader.utils.file_utils import ensure_file_exists
|
|
195
|
+
|
|
196
|
+
class YAMLReader(BaseReader):
|
|
197
|
+
supported_extensions = [".yaml", ".yml"]
|
|
198
|
+
|
|
199
|
+
def can_read(self, extension: str) -> bool:
|
|
200
|
+
return extension in self.supported_extensions
|
|
201
|
+
|
|
202
|
+
def read(self, path: str):
|
|
203
|
+
ensure_file_exists(path)
|
|
204
|
+
import yaml
|
|
205
|
+
with open(path, 'r', encoding='utf-8') as f:
|
|
206
|
+
return yaml.safe_load(f)
|
|
207
|
+
```
|
|
208
|
+
|
|
209
|
+
2. Register it in `unified_file_reader/registry.py`:
|
|
210
|
+
|
|
211
|
+
```python
|
|
212
|
+
from unified_file_reader.readers.yaml_reader import YAMLReader
|
|
213
|
+
|
|
214
|
+
readers = [
|
|
215
|
+
# ... existing readers ...
|
|
216
|
+
YAMLReader(),
|
|
217
|
+
]
|
|
218
|
+
```
|
|
219
|
+
|
|
220
|
+
3. Add tests in `tests/test_yaml_reader.py`
|
|
221
|
+
|
|
222
|
+
4. Update `supported_formats.py` with metadata
|
|
223
|
+
|
|
224
|
+
That's it! No changes needed to the core API.
|
|
225
|
+
|
|
226
|
+
## Testing
|
|
227
|
+
|
|
228
|
+
Run the test suite:
|
|
229
|
+
|
|
230
|
+
```bash
|
|
231
|
+
pytest
|
|
232
|
+
```
|
|
233
|
+
|
|
234
|
+
With coverage:
|
|
235
|
+
|
|
236
|
+
```bash
|
|
237
|
+
pytest --cov=unified_file_reader
|
|
238
|
+
```
|
|
239
|
+
|
|
240
|
+
Run specific tests:
|
|
241
|
+
|
|
242
|
+
```bash
|
|
243
|
+
pytest tests/test_api.py -v
|
|
244
|
+
```
|
|
245
|
+
|
|
246
|
+
## Development
|
|
247
|
+
|
|
248
|
+
Install development dependencies:
|
|
249
|
+
|
|
250
|
+
```bash
|
|
251
|
+
pip install -e ".[dev]"
|
|
252
|
+
```
|
|
253
|
+
|
|
254
|
+
Format code:
|
|
255
|
+
|
|
256
|
+
```bash
|
|
257
|
+
black unified_file_reader tests
|
|
258
|
+
isort unified_file_reader tests
|
|
259
|
+
```
|
|
260
|
+
|
|
261
|
+
Type checking:
|
|
262
|
+
|
|
263
|
+
```bash
|
|
264
|
+
mypy unified_file_reader
|
|
265
|
+
```
|
|
266
|
+
|
|
267
|
+
Linting:
|
|
268
|
+
|
|
269
|
+
```bash
|
|
270
|
+
flake8 unified_file_reader tests
|
|
271
|
+
```
|
|
272
|
+
|
|
273
|
+
## Contributing
|
|
274
|
+
|
|
275
|
+
Contributions are welcome! Please:
|
|
276
|
+
|
|
277
|
+
1. Fork the repository
|
|
278
|
+
2. Create a feature branch
|
|
279
|
+
3. Add tests for new functionality
|
|
280
|
+
4. Ensure all tests pass
|
|
281
|
+
5. Submit a pull request
|
|
282
|
+
|
|
283
|
+
## License
|
|
284
|
+
|
|
285
|
+
MIT License - see LICENSE file for details
|
|
286
|
+
|
|
287
|
+
## Changelog
|
|
288
|
+
|
|
289
|
+
### v0.1.0 (Initial Release)
|
|
290
|
+
- Initial release with support for CSV, JSON, TXT, XLSX, PDF, DOCX
|
|
291
|
+
- Clean Architecture implementation
|
|
292
|
+
- Full test coverage
|
|
293
|
+
- PyPI packaging
|
|
294
|
+
|
|
295
|
+
## Support
|
|
296
|
+
|
|
297
|
+
For issues, questions, or suggestions, please open an issue on GitHub.
|