docs: add README

README.md

@@ -0,0 +1,100 @@
+
+
+# python-mfiles
+
+A Python wrapper around the M-Files REST API. This package simplifies searching, uploading, downloading, and managing objects in M-Files vaults. It abstracts away M-Files property IDs, allowing you to interact with object types, classes, and properties using human-readable names instead of numeric IDs.
+
+## Installation
+
+Install the package using `pip`:
+
+```bash
+pip install mfiles
+```
+
+*Note: The package requires `requests` and Python 3.5+.*
+
+## Authentication
+
+The `MFilesClient` supports three methods for authentication, evaluated in order:
+
+1. **Programmatic:** Pass credentials directly during initialization.
+2. **Environment Variables:** Set `MFILES_URL`, `MFILES_USER`, `MFILES_PASS`, and `MFILES_VAULT`.
+3. **Interactive:** If no credentials are provided, the client will securely prompt for your username and password using `input()` and `getpass()`.
+
+## Usage
+
+### Initialization
+```python
+import mfiles
+
+client = mfiles.MFilesClient(
+    server="https://your-mfiles-server.com/REST/",
+    user="your_username",
+    password="your_password",
+    vault="{your-vault-guid}"
+)
+```
+
+### Upload a File
+```python
+client.upload_file(
+    "path/to/report.pdf",
+    object_type="Document",
+    object_class="General document",
+    extra_info={
+        "Document Type": "Report",
+        "Document Title": "Q3 Financials"
+    }
+)
+```
+
+### Download a File
+```python
+# Quick download by name (fetches the top search result)
+client.download_file_name("report.pdf")
+
+# Precise download using object/file IDs
+client.download_file(
+    local_path="downloads/report.pdf",
+    object_type=0,
+    object_id=12345,
+    file_id=1
+)
+```
+
+### Search & Object Management
+```python
+# Quick search
+results = client.quick_search("invoice 2024")
+
+# Check out / Check in
+client.check_out(object_type=0, object_id=12345)
+client.check_in(object_type=0, object_id=12345)
+
+# Delete (flags for deletion) / Destroy (permanent removal)
+client.delete_object(object_type=0, object_id=12345)
+client.destroy_object(object_type=0, object_id=12345)
+```
+
+## Features
+- 🔍 Quick & advanced vault search
+- 📤 Upload & download files with automatic metadata handling
+- 📦 Create, check-out, check-in, delete, and permanently destroy objects
+- 🔑 Automatic translation of object types, classes, and property names to server IDs
+- 🌐 Full REST API wrapper with session management and token handling
+- 🐍 Clean Pythonic interface with comprehensive error handling (`MFilesException`)
+
+## Documentation
+Full API documentation, examples, and reference guides are available on [Read the Docs](https://mfiles.readthedocs.io/en/latest/).
+
+## Development & Testing
+To run the test suite and linters locally:
+```bash
+pip install -r dev_requirements.txt
+python -m pytest
+pylint . --recursive=y
+```
+
+## License
+MIT License. See the [LICENSE](LICENSE) file for details.