### Install python-magic using pip

Source: https://github.com/ahupp/python-magic/blob/master/README.md

Install the latest stable version of python-magic from PyPI using pip.

```bash
pip install python-magic
```

--------------------------------

### Install libmagic on Debian/Ubuntu

Source: https://github.com/ahupp/python-magic/blob/master/README.md

Install the libmagic shared library on Debian-based systems using apt-get.

```bash
sudo apt-get install libmagic1
```

--------------------------------

### Install libmagic on Fedora/RHEL

Source: https://github.com/ahupp/python-magic/blob/master/_autodocs/loader-module.md

Install the file-libs package on Fedora or RHEL systems using yum.

```bash
sudo yum install file-libs
```

--------------------------------

### Verify libmagic Installation

Source: https://github.com/ahupp/python-magic/blob/master/_autodocs/loader-module.md

Verify the libmagic installation by attempting to load the library using python-magic.

```bash
python -c "from magic import loader; print(loader.load_lib())"
```

--------------------------------

### Example Usage of setparam and getparam

Source: https://github.com/ahupp/python-magic/blob/master/_autodocs/api-reference-magic-constants.md

Demonstrates how to use setparam() to increase the maximum bytes read and getparam() to retrieve the current value.

```APIDOC
## Example Usage

```python
import magic

m = magic.Magic()
try:
    # Increase max bytes to read for better detection of large files
    m.setparam(magic.MAGIC_PARAM_BYTES_MAX, 1048576)  # 1MB
    
    # Check current value
    current = m.getparam(magic.MAGIC_PARAM_BYTES_MAX)
    print(f"Max bytes: {current}")
except MagicException as e:
    print(f"Parameter not supported: {e}")
```
```

--------------------------------

### Install libmagic on macOS using MacPorts

Source: https://github.com/ahupp/python-magic/blob/master/README.md

Install the libmagic library on macOS using MacPorts.

```bash
port install file
```

--------------------------------

### Magic Class Methods

Source: https://github.com/ahupp/python-magic/blob/master/_autodocs/INDEX.md

Demonstrates how to create an instance of the Magic class and use its methods for file type detection from files, buffers, and file descriptors. It also shows how to get and set parameters.

```APIDOC
## Magic Class

### Description
Provides an object-oriented interface for file type detection.

### Methods

#### `__init__(self, mime=False, uncompress=True, check_elf=False, ...)`
Creates an instance of the Magic class with specified options.

#### `from_file(self, filename: str | bytes | PathLike) -> str`
Detects the MIME type of a file specified by its filename.

#### `from_buffer(self, buffer: bytes | str) -> str`
Detects the MIME type of data provided in a buffer.

#### `from_descriptor(self, fd: int) -> str`
Detects the MIME type of a file using its file descriptor.

#### `getparam(self, param: int) -> int`
Retrieves the value of a specific parameter.

#### `setparam(self, param: int, val: int) -> int`
Sets the value of a specific parameter.
```

--------------------------------

### Usage Example for FileMagic

Source: https://github.com/ahupp/python-magic/blob/master/_autodocs/types.md

Demonstrates how to use the FileMagic namedtuple obtained from magic.detect_from_filename, including accessing fields, unpacking, converting to a dictionary, and iterating.

```python
import magic

# From compatibility layer (deprecated)
result = magic.detect_from_filename('document.pdf')
print(f"Type: {result.name}")          # 'PDF document, version 1.2'
print(f"MIME: {result.mime_type}")     # 'application/pdf'
print(f"Encoding: {result.encoding}")  # 'binary'

# Unpacking
mime, encoding, name = result
print(f"{mime}: {name}")

# As dictionary
info = result._asdict()
print(info)
# {'mime_type': 'application/pdf', 'encoding': 'binary', 'name': 'PDF document, version 1.2'}

# Iteration
for field_name, field_value in zip(result._fields, result):
    print(f"{field_name}: {field_value}")
```

--------------------------------

### Install libmagic on macOS using Homebrew

Source: https://github.com/ahupp/python-magic/blob/master/README.md

Install the libmagic library on macOS using the Homebrew package manager.

```bash
brew install libmagic
```

--------------------------------

### Combined File Detection (MIME, Encoding, Description)

Source: https://github.com/ahupp/python-magic/blob/master/_autodocs/usage-guide.md

Demonstrates how to get multiple pieces of file information (MIME type, encoding, and a human-readable description) simultaneously by creating separate Magic instances for each detection type.

```python
import magic

# Get MIME type, encoding, and description all at once
m_mime = magic.Magic(mime=True)
m_enc = magic.Magic(mime_encoding=True)
m_desc = magic.Magic()

filename = 'document.pdf'
mime_type = m_mime.from_file(filename)
encoding = m_enc.from_file(filename)
description = m_desc.from_file(filename)

print(f"MIME: {mime_type}")
print(f"Encoding: {encoding}")
print(f"Description: {description}")
```

--------------------------------

### Example Usage of FileMagic Namedtuple

Source: https://github.com/ahupp/python-magic/blob/master/_autodocs/compat-layer.md

Demonstrates how to use the FileMagic namedtuple to access file information by attribute, unpacking, and iteration.

```python
import magic

result = magic.detect_from_filename('document.pdf')

# Access as attributes
print(result.mime_type)  # 'application/pdf'
print(result.encoding)   # 'binary'
print(result.name)       # 'PDF document, version 1.2'

# Unpack tuple
mime, encoding, name = result
print(f"{mime}: {encoding}")  # 'application/pdf: binary'

# Iterate
for field in result:
    print(field)
```

--------------------------------

### Project Navigation Structure

Source: https://github.com/ahupp/python-magic/blob/master/_autodocs/COVERAGE.md

Illustrates the hierarchical organization of documentation files within the python-magic project, showing the relationship between the master index, API references, configuration guides, advanced topics, and usage guides.

```markdown
INDEX.md (Master index)
├── API Reference
│   ├── api-reference-magic-class.md
│   ├── api-reference-module-functions.md
│   └── api-reference-magic-constants.md
├── Configuration & Behavior
│   ├── configuration.md
│   ├── types.md
│   └── exceptions.md
├── Advanced Topics
│   ├── compat-layer.md
│   ├── loader-module.md
│   └── ctypes-bindings.md
└── Usage & Examples
    └── usage-guide.md
```

--------------------------------

### Example: Adjusting Max Bytes for File Detection

Source: https://github.com/ahupp/python-magic/blob/master/_autodocs/api-reference-magic-constants.md

Demonstrates how to increase the maximum bytes read for better detection of large files using setparam() and verify the change with getparam(). Catches MagicException if the parameter is not supported.

```python
import magic

m = magic.Magic()
try:
    # Increase max bytes to read for better detection of large files
    m.setparam(magic.MAGIC_PARAM_BYTES_MAX, 1048576)  # 1MB
    
    # Check current value
    current = m.getparam(magic.MAGIC_PARAM_BYTES_MAX)
    print(f"Max bytes: {current}")
except MagicException as e:
    print(f"Parameter not supported: {e}")
```

--------------------------------

### Get Textual File Description

Source: https://github.com/ahupp/python-magic/blob/master/_autodocs/usage-guide.md

Use `magic.from_file()` to get a human-readable description of a file's type. This works for various file formats.

```python
import magic

# Get human-readable file type description
result = magic.from_file('document.pdf')
print(result)
# Output: 'PDF document, version 1.2'

# Works with any file type
result = magic.from_file('image.png')
# Output: 'PNG image data, 800 x 600, 8-bit/color RGBA, non-interlaced'
```

--------------------------------

### Basic Magic Class Usage

Source: https://github.com/ahupp/python-magic/blob/master/_autodocs/api-reference-magic-class.md

Demonstrates basic usage of the Magic class for file type detection. Instantiate with desired options and use `from_file` to get results. Supports MIME types, encoding detection, and analyzing compressed files.

```python
import magic

# Basic usage with MIME types
m = magic.Magic(mime=True)
file_type = m.from_file('document.pdf')
# Returns: 'application/pdf'

# Detect encoding
m_encoding = magic.Magic(mime_encoding=True)
encoding = m_encoding.from_file('text_file.txt')
# Returns: 'utf-8'

# Uncompress and analyze compressed files
m_uncompress = magic.Magic(uncompress=True)
result = m_uncompress.from_file('archive.gz')
# Returns description of contents, not the gzip format itself

# Combine multiple options
m_multi = magic.Magic(mime=True, uncompress=True, follow_symlinks=True)
result = m_multi.from_file('link_to_file.tar.gz')
```

--------------------------------

### Get and Set Magic Parameters

Source: https://github.com/ahupp/python-magic/blob/master/_autodocs/INDEX.md

Retrieve a parameter value using getparam or set a parameter using setparam.

```python
# Get/set parameters
value: int = m.getparam(param: int) -> int
m.setparam(param: int, val: int) -> int
```

--------------------------------

### Get MIME Type for Web Server

Source: https://github.com/ahupp/python-magic/blob/master/_autodocs/INDEX.md

Instantiate Magic with mime=True to retrieve the MIME type of a file, useful for web servers.

```python
m = magic.Magic(mime=True)
mime_type = m.from_file('static/file.pdf')
```

--------------------------------

### Basic File Type Detection with python-magic

Source: https://github.com/ahupp/python-magic/blob/master/_autodocs/INDEX.md

Use module-level functions for simple file type detection. Specify `mime=True` to get the MIME type instead of a human-readable description. For more complex configurations, instantiate the `Magic` class.

```python
import magic

# Get file type description
magic.from_file('document.pdf')
# Returns: 'PDF document, version 1.2'

# Get MIME type
magic.from_file('document.pdf', mime=True)
# Returns: 'application/pdf'

# For more control, create a Magic instance
m = magic.Magic(mime=True, uncompress=True)
m.from_file('archive.tar.gz')
```

--------------------------------

### Process Uploaded Files Using File Descriptors

Source: https://github.com/ahupp/python-magic/blob/master/_autodocs/usage-guide.md

Demonstrates a pattern for processing uploaded files in web frameworks, focusing on detecting file type and MIME type from a file descriptor without buffering the entire file. It includes an example of raising an error for disallowed file types and a basic Flask route.

```python
import magic
from io import BytesIO

# Typical web framework pattern
def process_upload(file_obj):
    # Get file type without buffering entire file
    file_type = magic.from_descriptor(file_obj.fileno())
    
    # Check if it's allowed
    mime_type = magic.from_descriptor(file_obj.fileno(), mime=True)
    if not mime_type.startswith('image/'):
        raise ValueError(f"Expected image, got {mime_type}")
    
    # Process file...
    file_obj.seek(0)
    data = file_obj.read()
    return data

# Flask example
from flask import Flask, request

app = Flask(__name__)

@app.route('/upload', methods=['POST'])
def upload():
    file = request.files['file']
    try:
        data = process_upload(file.stream)
        return {'status': 'ok', 'size': len(data)}
    except ValueError as e:
        return {'error': str(e)}, 400
```

--------------------------------

### Get Multiple Matching Patterns

Source: https://github.com/ahupp/python-magic/blob/master/_autodocs/usage-guide.md

Configures a Magic instance with `keep_going=True` to retrieve all matching patterns for a file, not just the first one. This is useful for files that might match multiple definitions in the magic database.

```python
import magic

# Get all matching patterns
m = magic.Magic(keep_going=True)
result = m.from_file('complex_file.bin')
# Output may contain multiple matches separated by newlines
```

--------------------------------

### Check libmagic Version

Source: https://github.com/ahupp/python-magic/blob/master/_autodocs/usage-guide.md

Provides a Python snippet to retrieve the installed libmagic version and check for support of specific features like `MAGIC_EXTENSION`.

```python
import magic

try:
    version = magic.version()
    print(f"libmagic version: {version}")
    
    # Check for feature support
    if version >= 524:
        print("MAGIC_EXTENSION is supported")
    else:
        print("MAGIC_EXTENSION not supported")
except NotImplementedError:
    print("magic_version not available")
```

--------------------------------

### Configure Custom Library Paths for python-magic

Source: https://github.com/ahupp/python-magic/blob/master/_autodocs/loader-module.md

Set environment variables LD_LIBRARY_PATH for Linux or DYLD_LIBRARY_PATH for macOS to specify custom installation paths for libmagic before importing the magic module.

```python
import os
import ctypes

# Set library path before importing magic
os.environ['LD_LIBRARY_PATH'] = '/custom/lib'  # Linux
os.environ['DYLD_LIBRARY_PATH'] = '/custom/lib'  # macOS

import magic
```

--------------------------------

### Check Specific MagicException Error Conditions

Source: https://github.com/ahupp/python-magic/blob/master/_autodocs/exceptions.md

Provides an example of how to check the error message within a MagicException to identify specific failure conditions, such as a missing magic database.

```python
# Checking specific error conditions
try:
    m = magic.Magic()
except magic.MagicException as e:
    if "could not find any magic files" in str(e.message):
        print("libmagic database is missing")
        print("Install it with: apt-get install libmagic1")
    else:
        print(f"Other error: {e.message}")
```

--------------------------------

### Python: Get File Extension using MAGIC_EXTENSION

Source: https://github.com/ahupp/python-magic/blob/master/_autodocs/api-reference-magic-constants.md

Returns a slash-separated list of valid file extensions. Requires libmagic 5.24+. Use extension=True parameter.

```python
import magic

m = magic.Magic(extension=True)
result = m.from_file('document.pdf')
# Returns: 'pdf/pdf' or similar
```

--------------------------------

### Union Types for File Parameters

Source: https://github.com/ahupp/python-magic/blob/master/_autodocs/types.md

Illustrates the use of union types for the 'filename' and 'buffer' parameters in python-magic functions. It shows examples of passing strings, bytes, and PathLike objects.

```python
import magic

# filename: Union[str, bytes, PathLike]
magic.from_file('document.pdf')  # str
magic.from_file(b'document.pdf')  # bytes
magic.from_file(Path('document.pdf'))  # PathLike

# buffer: Union[bytes, str]
magic.from_buffer(b'...')  # bytes
magic.from_buffer('...')  # str (converted to UTF-8)
```

--------------------------------

### Migrate Magic Instance Creation: Old vs New

Source: https://github.com/ahupp/python-magic/blob/master/_autodocs/compat-layer.md

Compares the deprecated `magic.open` and `m.load` with the recommended `magic.Magic` constructor for creating a magic instance.

```python
import magic
m = magic.open(magic.MAGIC_MIME)
m.load()
result = m.file('file.pdf')
m.close()
```

```python
import magic
m = magic.Magic(mime=True)
result = m.from_file('file.pdf')
# No need to call close() manually
```

--------------------------------

### Handle MagicException During Initialization

Source: https://github.com/ahupp/python-magic/blob/master/_autodocs/exceptions.md

Demonstrates basic exception handling when initializing the Magic class, specifically catching MagicException if the magic database cannot be loaded.

```python
import magic

# Basic exception handling
try:
    m = magic.Magic(magic_file="/invalid/path/to/magic")
except magic.MagicException as e:
    print(f"Failed to initialize Magic: {e.message}")
```

--------------------------------

### Configure Multiple Matches with Python-Magic

Source: https://github.com/ahupp/python-magic/blob/master/_autodocs/configuration.md

Use `keep_going=True` to retrieve all matching file type descriptions instead of stopping at the first match. The default `keep_going=False` returns only the first match.

```python
import magic

# Single match (default)
m = magic.Magic(keep_going=False)
result = m.from_file('file.bin')
# Output: First matching description

# All matches
m = magic.Magic(keep_going=True)
result = m.from_file('file.bin')
# Output: Multiple descriptions (usually on separate lines)
```

--------------------------------

### open

Source: https://github.com/ahupp/python-magic/blob/master/_autodocs/compat-layer.md

Creates and returns a Magic instance from the compatibility layer. This function is deprecated and emits a `PendingDeprecationWarning`.

```APIDOC
## open

### Description
Creates and returns a Magic instance from the compatibility layer.

### Parameters
#### Path Parameters
- **flags** (int) - Required - Bitwise OR of flag constants (MAGIC_MIME, MAGIC_MIME_ENCODING, etc.).

### Returns
`Magic` — A compatibility layer Magic instance with methods: file(), descriptor(), buffer(), error(), setflags(), load(), compile(), check(), list(), errno(), getparam(), setparam(), close()

### Raises
- Returns None if magic_open fails (instead of raising an exception)

### Example
```python
import magic
import warnings

warnings.filterwarnings('ignore', category=PendingDeprecationWarning)

# Create instance with MIME type flag
m = magic.open(magic.MAGIC_MIME_TYPE)
if m is None:
    print("Failed to create magic instance")
else:
    m.load()  # Load default magic database
    result = m.file('document.pdf')
    print(result)  # 'application/pdf'
    m.close()

# Equivalent modern API
m = magic.Magic(mime=True)  # Recommended
result = m.from_file('document.pdf')
# No need to call close() manually
```
```

--------------------------------

### Detect File Type

Source: https://github.com/ahupp/python-magic/blob/master/_autodocs/INDEX.md

Use this snippet to get the general file type of a given file.

```python
import magic
file_type = magic.from_file('document.pdf')
```

--------------------------------

### Get Library Version

Source: https://github.com/ahupp/python-magic/blob/master/_autodocs/INDEX.md

Retrieve the version of the underlying magic library using the version function.

```python
# Version
version: int = magic.version()
```

--------------------------------

### Magic.getparam

Source: https://github.com/ahupp/python-magic/blob/master/_autodocs/api-reference-magic-class.md

Gets the current value of a libmagic parameter. This method is available for libmagic versions 5.30 and later.

```APIDOC
## Magic.getparam

### Description
Gets the current value of a libmagic parameter. Only available if libmagic supports the magic_getparam function (libmagic 5.30+).

### Method
`getparam(self, param: int) -> int`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
* **param** (int) - Required - The parameter identifier. Use constants like MAGIC_PARAM_NAME_MAX, MAGIC_PARAM_INDIR_MAX, etc.

### Request Example
```python
import magic

m = magic.Magic()
try:
    # Get the current name/use recursion limit
    limit = m.getparam(magic.MAGIC_PARAM_NAME_MAX)
    print(f"Current MAGIC_PARAM_NAME_MAX: {limit}")
except MagicException as e:
    print(f"Failed to get parameter: {e}")
```

### Response
#### Success Response (200)
* **return value** (int) - The current value of the parameter.

#### Response Example
```json
32
```

### Errors
* `NotImplementedError` — if the libmagic library does not support magic_getparam
* `MagicException` — if the parameter is unknown
```

--------------------------------

### Configure Following Symbolic Links with Python-Magic

Source: https://github.com/ahupp/python-magic/blob/master/_autodocs/configuration.md

Set `follow_symlinks=True` to identify the target file type when encountering a symbolic link, or `False` to report the file as a symbolic link. This requires the `os` module for creating demonstration symlinks.

```python
import magic
import os

# Create a symlink for demonstration
os.symlink('document.pdf', 'link.pdf')

# Don't follow symlinks (default)
m = magic.Magic(follow_symlinks=False)
result = m.from_file('link.pdf')
# Output: 'symbolic link to ...'

# Follow symlinks
m = magic.Magic(follow_symlinks=True)
result = m.from_file('link.pdf')
# Output: 'PDF document, version 1.2'
```

--------------------------------

### Identify File Type with MIME Type

Source: https://github.com/ahupp/python-magic/blob/master/README.md

Call `magic.from_file()` with `mime=True` to get the MIME type of the file.

```python
>>> magic.from_file("testdata/test.pdf", mime=True)
'application/pdf'
```

--------------------------------

### Initialize Magic Instance

Source: https://github.com/ahupp/python-magic/blob/master/_autodocs/api-reference-magic-class.md

Creates a new Magic instance with libmagic wrapper. Customize detection behavior using various boolean flags. Ensure libmagic version is 5.24+ if using the 'extension' option.

```python
def __init__(
    self,
    mime: bool = False,
    magic_file: Optional[str] = None,
    mime_encoding: bool = False,
    keep_going: bool = False,
    uncompress: bool = False,
    raw: bool = False,
    extension: bool = False,
    follow_symlinks: bool = False,
    check_tar: bool = True,
    check_soft: bool = True,
    check_apptype: bool = True,
    check_elf: bool = True,
    check_text: bool = True,
    check_cdf: bool = True,
    check_csv: bool = True,
    check_encoding: bool = True,
    check_json: bool = True,
    check_simh: bool = True,
) -> None
```

--------------------------------

### Set DYLD_LIBRARY_PATH for non-standard macOS locations

Source: https://github.com/ahupp/python-magic/blob/master/_autodocs/loader-module.md

If libmagic is installed in a non-standard location on macOS, set the DYLD_LIBRARY_PATH environment variable.

```bash
export DYLD_LIBRARY_PATH=/opt/homebrew/lib
```

--------------------------------

### Handle NotImplementedError for Unsupported Features

Source: https://github.com/ahupp/python-magic/blob/master/_autodocs/exceptions.md

Catch `NotImplementedError` when using features not supported by the installed libmagic version, such as extensions or specific parameters.

```python
import magic

try:
    m = magic.Magic(extension=True)
except NotImplementedError as e:
    print("MAGIC_EXTENSION is not supported in this version of libmagic")

try:
    ver = magic.version()
except NotImplementedError as e:
    print("magic_version not implemented in this libmagic")

try:
    m = magic.Magic()
    m.setparam(magic.MAGIC_PARAM_NAME_MAX, 64)
except NotImplementedError as e:
    print("setparam not implemented")
```

--------------------------------

### Configure Output Format: MIME vs. Textual Description

Source: https://github.com/ahupp/python-magic/blob/master/_autodocs/configuration.md

Use the `mime` parameter to switch between human-readable descriptions and MIME types for file identification. Set to `True` for MIME types, `False` for descriptions.

```python
import magic

# Textual description
m_desc = magic.Magic(mime=False)
result = m_desc.from_file('document.pdf')
# Output: 'PDF document, version 1.2'

# MIME type
m_mime = magic.Magic(mime=True)
result = m_mime.from_file('document.pdf')
# Output: 'application/pdf'
```

--------------------------------

### Instantiate Magic Class

Source: https://github.com/ahupp/python-magic/blob/master/_autodocs/INDEX.md

Create an instance of the Magic class with optional parameters like mime, uncompress, and check_elf.

```python
from magic import Magic, MagicException

# Create instance
m = Magic(mime=True, uncompress=True, check_elf=False, ...)
```

--------------------------------

### Create Magic instance with flags (Deprecated)

Source: https://github.com/ahupp/python-magic/blob/master/_autodocs/compat-layer.md

Creates and returns a Magic instance from the compatibility layer. Use magic.Magic() for modern API. The instance has methods like file(), descriptor(), buffer(), etc.

```python
import magic
import warnings

warnings.filterwarnings('ignore', category=PendingDeprecationWarning)

# Create instance with MIME type flag
m = magic.open(magic.MAGIC_MIME_TYPE)
if m is None:
    print("Failed to create magic instance")
else:
    m.load()  # Load default magic database
    result = m.file('document.pdf')
    print(result)  # 'application/pdf'
    m.close()

# Equivalent modern API
m = magic.Magic(mime=True)  # Recommended
result = m.from_file('document.pdf')
# No need to call close() manually
```

--------------------------------

### Detect File Type with Pathlib

Source: https://github.com/ahupp/python-magic/blob/master/_autodocs/usage-guide.md

Demonstrates using python-magic directly with `pathlib.Path` objects for single files and iterating through a directory to detect PDF types.

```python
import magic
from pathlib import Path

# Works directly with Path objects
pdf = Path('document.pdf')
result = magic.from_file(pdf)  # Path is automatically converted
print(result)

# Detect all PDFs in directory
pdf_dir = Path('documents')
for pdf_file in pdf_dir.glob('*.pdf'):
    mime = magic.from_file(pdf_file, mime=True)
    print(f"{pdf_file.name}: {mime}")
```

--------------------------------

### Get libmagic Version with ctypes

Source: https://github.com/ahupp/python-magic/blob/master/_autodocs/ctypes-bindings.md

Binds to `magic_version` to retrieve the libmagic library version. Requires libmagic support for this function. The version is returned as an integer.

```python
_has_version = False
if hasattr(libmagic, "magic_version"):
    _has_version = True
    magic_version = libmagic.magic_version
    magic_version.restype = c_int
    magic_version.argtypes = []

def version():
    if not _has_version:
        raise NotImplementedError("magic_version not implemented")
    return magic_version()
```

--------------------------------

### Load Magic Database

Source: https://github.com/ahupp/python-magic/blob/master/_autodocs/ctypes-bindings.md

Loads a magic database file. If filename is NULL, loads the default database. Raises MagicException on error.

```python
_magic_load = libmagic.magic_load
_magic_load.restype = c_int
_magic_load.argtypes = [magic_t, c_char_p]
_magic_load.errcheck = errorcheck_negative_one

def magic_load(cookie, filename):
    return _magic_load(cookie, coerce_filename(filename))
```

--------------------------------

### Advanced File Type Identification with MIME and Decompression

Source: https://github.com/ahupp/python-magic/blob/master/README.md

Combine `mime=True` and `uncompress=True` when creating a `Magic` instance to get the MIME type of decompressed content.

```python
>>> f = magic.Magic(mime=True, uncompress=True)
>>> f.from_file('testdata/test.gz')
'text/plain'
```

--------------------------------

### PathLike Support for File Operations

Source: https://github.com/ahupp/python-magic/blob/master/_autodocs/types.md

Demonstrates how python-magic accepts os.PathLike objects, such as pathlib.Path, for file operations. It also shows how to use Path.open() with magic.from_descriptor.

```python
import magic
from pathlib import Path

# Works with pathlib.Path
p = Path('document.pdf')
result = magic.from_file(p)

# Also works with Path.open()
with (Path('document.pdf')).open('rb') as f:
    result = magic.from_descriptor(f.fileno())
```

--------------------------------

### Get libmagic Library Version

Source: https://github.com/ahupp/python-magic/blob/master/_autodocs/api-reference-module-functions.md

The `version` function retrieves the version number of the underlying libmagic library. This function may raise a NotImplementedError if the library does not support it.

```python
import magic

try:
    lib_version = magic.version()
    print(f"libmagic version: {lib_version}")
    # Output: libmagic version: 530
    
    # Check if version supports certain features
    if lib_version >= 524:
        print("MAGIC_EXTENSION is supported")
except NotImplementedError:
    print("magic_version not available in this libmagic")
```

--------------------------------

### Magic Class Constructor

Source: https://github.com/ahupp/python-magic/blob/master/_autodocs/api-reference-magic-class.md

Initializes a new Magic instance, which wraps the libmagic C library for file type detection. Various options can be configured to customize the detection process, such as returning MIME types, handling compressed files, or following symbolic links.

```APIDOC
## Magic.__init__

### Description
Creates a new Magic instance with libmagic wrapper.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **mime** (bool) - Optional - If True, return MIME types instead of human-readable descriptions.
- **magic_file** (Optional[str]) - Optional - Path to a custom magic database file. If None, uses system default.
- **mime_encoding** (bool) - Optional - If True, return the character encoding (codec) of the file.
- **keep_going** (bool) - Optional - If True, don't stop at the first match; continue and return all matches.
- **uncompress** (bool) - Optional - If True, attempt to look inside compressed files and identify their contents.
- **raw** (bool) - Optional - If True, do not attempt to decode non-printable characters.
- **extension** (bool) - Optional - If True, return a slash-separated list of valid extensions for the detected file type. Requires libmagic 5.24+.
- **follow_symlinks** (bool) - Optional - If True, follow symbolic links when checking files.
- **check_tar** (bool) - Optional - If False, disable tar file detection (MAGIC_NO_CHECK_TAR).
- **check_soft** (bool) - Optional - If False, disable soft magic entries (MAGIC_NO_CHECK_SOFT).
- **check_apptype** (bool) - Optional - If False, disable application type detection (MAGIC_NO_CHECK_APPTYPE).
- **check_elf** (bool) - Optional - If False, disable ELF binary detection details (MAGIC_NO_CHECK_ELF).
- **check_text** (bool) - Optional - If False, disable ASCII/text file detection (MAGIC_NO_CHECK_TEXT).
- **check_cdf** (bool) - Optional - If False, disable CDF file detection (MAGIC_NO_CHECK_CDF).
- **check_csv** (bool) - Optional - If False, disable CSV file detection (MAGIC_NO_CHECK_CSV).
- **check_encoding** (bool) - Optional - If False, disable text encoding detection (MAGIC_NO_CHECK_ENCODING).
- **check_json** (bool) - Optional - If False, disable JSON file detection (MAGIC_NO_CHECK_JSON).
- **check_simh** (bool) - Optional - If False, disable SIMH tape file detection (MAGIC_NO_CHECK_SIMH).

### Request Example
```python
import magic

# Basic usage with MIME types
m = magic.Magic(mime=True)
file_type = m.from_file('document.pdf')
# Returns: 'application/pdf'

# Detect encoding
m_encoding = magic.Magic(mime_encoding=True)
encoding = m_encoding.from_file('text_file.txt')
# Returns: 'utf-8'

# Uncompress and analyze compressed files
m_uncompress = magic.Magic(uncompress=True)
result = m_uncompress.from_file('archive.gz')
# Returns description of contents, not the gzip format itself

# Combine multiple options
m_multi = magic.Magic(mime=True, uncompress=True, follow_symlinks=True)
result = m_multi.from_file('link_to_file.tar.gz')
```

### Response
#### Success Response (None)
None. Initializes the Magic instance with internal cookie and lock attributes.

#### Response Example
None

### Raises
- `MagicException` — if the magic database cannot be loaded or if magic_open fails
- `NotImplementedError` — if extension=True is requested but libmagic version is less than 5.24
```

--------------------------------

### macOS libmagic Library Candidates

Source: https://github.com/ahupp/python-magic/blob/master/_autodocs/loader-module.md

Generates libmagic library paths for macOS systems, checking common installation locations for Homebrew and MacPorts. This is used internally by load_lib().

```python
from magic import loader

# Example usage (internal to loader.load_lib)
# for candidate in loader._lib_candidates_macos():
#     print(candidate)
```

--------------------------------

### Migrate Buffer Detection: Old vs New

Source: https://github.com/ahupp/python-magic/blob/master/_autodocs/compat-layer.md

Compares the deprecated `detect_from_content` with the recommended `magic.from_buffer` for detecting MIME type from raw data.

```python
import magic
with open('file.pdf', 'rb') as f:
    data = f.read(2048)
    result = magic.detect_from_content(data)
    mime = result.mime_type
```

```python
import magic
with open('file.pdf', 'rb') as f:
    data = f.read(2048)
    mime = magic.from_buffer(data, mime=True)
```

--------------------------------

### Optimize Performance by Reusing Magic Instance

Source: https://github.com/ahupp/python-magic/blob/master/_autodocs/INDEX.md

For performance-critical applications, create a single Magic instance and reuse it for multiple file analyses.

```python
m = magic.Magic(mime=True)
for file in files:
    mime = m.from_file(file)
```

--------------------------------

### Raw Output Without Decoding

Source: https://github.com/ahupp/python-magic/blob/master/_autodocs/api-reference-magic-constants.md

Use `raw=True` to get the raw output from the `libmagic` library without decoding special characters. This is useful for debugging or specific low-level analysis.

```python
import magic

# Raw output without decoding special characters
m = magic.Magic(raw=True)
# Flags: MAGIC_RAW
```

--------------------------------

### Set/Get libmagic Parameters with ctypes

Source: https://github.com/ahupp/python-magic/blob/master/_autodocs/ctypes-bindings.md

Binds to `magic_setparam` and `magic_getparam` for setting and getting libmagic internal parameters. Requires libmagic 5.30 or later. Ensure `libmagic` is available and has these functions.

```python
_has_param = False
if hasattr(libmagic, "magic_setparam") and hasattr(libmagic, "magic_getparam"):
    _has_param = True
    _magic_setparam = libmagic.magic_setparam
    _magic_setparam.restype = c_int
    _magic_setparam.argtypes = [magic_t, c_int, POINTER(c_size_t)]
    _magic_setparam.errcheck = errorcheck_negative_one
    
    _magic_getparam = libmagic.magic_getparam
    _magic_getparam.restype = c_int
    _magic_getparam.argtypes = [magic_t, c_int, POINTER(c_size_t)]
    _magic_getparam.errcheck = errorcheck_negative_one

def magic_setparam(cookie, param, val):
    if not _has_param:
        raise NotImplementedError("magic_setparam not implemented")
    v = c_size_t(val)
    return _magic_setparam(cookie, param, byref(v))

def magic_getparam(cookie, param):
    if not _has_param:
        raise NotImplementedError("magic_getparam not implemented")
    val = c_size_t()
    _magic_getparam(cookie, param, byref(val))
    return val.value
```

--------------------------------

### Handle Version-Specific Features

Source: https://github.com/ahupp/python-magic/blob/master/_autodocs/usage-guide.md

Demonstrates a function that attempts to use version-specific features (like extensions) and falls back to basic detection if the feature is not supported.

```python
import magic

def detect_with_extensions(filename):
    """Try to detect with extensions, fall back if not supported."""
    
    try:
        # Try with extensions (requires libmagic 5.24+)
        m = magic.Magic(extension=True)
        result = m.from_file(filename)
        return f"extensions: {result}"
    except NotImplementedError:
        # Fall back to basic detection
        result = magic.from_file(filename)
        return f"type: {result}"
```

--------------------------------

### Troubleshoot Missing Magic Files

Source: https://github.com/ahupp/python-magic/blob/master/_autodocs/configuration.md

If you encounter 'could not find any magic files' errors, this snippet attempts to load the magic database from common locations. It iterates through a list of potential paths and uses the first one that is found.

```python
import magic

# Try common locations
magic_db_paths = [
    '/usr/share/file/magic.mgc',
    '/usr/lib/file/magic.mgc',
    '/etc/magic',
]

m = None
for path in magic_db_paths:
    try:
        m = magic.Magic(magic_file=path)
        break
    except magic.MagicException:
        continue

if m is None:
    print("Could not find magic database")
else:
    result = m.from_file('document.pdf')
    print(result)
```

--------------------------------

### Creating a Custom Magic Instance for Advanced Options

Source: https://github.com/ahupp/python-magic/blob/master/_autodocs/api-reference-module-functions.md

Use this pattern when module-level functions are insufficient. Create a custom Magic instance to specify additional detection parameters beyond the default mime setting.

```python
import magic

# Module-level function: limited to mime parameter
result1 = magic.from_file('archive.gz', mime=True)

# If you need more options (e.g., uncompress), create your own Magic instance
m = magic.Magic(mime=True, uncompress=True)
result2 = m.from_file('archive.gz')
```

--------------------------------

### Get libmagic Parameter

Source: https://github.com/ahupp/python-magic/blob/master/_autodocs/api-reference-magic-class.md

Use `getparam` to retrieve the current value of a libmagic parameter. This method requires libmagic version 5.30 or higher. It can raise `NotImplementedError` or `MagicException` if the parameter is unsupported or unknown.

```python
import magic

m = magic.Magic()
try:
    # Get the current name/use recursion limit
    limit = m.getparam(magic.MAGIC_PARAM_NAME_MAX)
    print(f"Current MAGIC_PARAM_NAME_MAX: {limit}")
except magic.MagicException as e:
    print(f"Failed to get parameter: {e}")
```

--------------------------------

### Specify Custom Magic Database Path

Source: https://github.com/ahupp/python-magic/blob/master/_autodocs/loader-module.md

Instantiate the Magic class with a custom magic_file argument to point to a non-standard magic database location.

```python
import magic

m = magic.Magic(magic_file='/custom/path/to/magic')
```

--------------------------------

### magic_setparam / magic_getparam

Source: https://github.com/ahupp/python-magic/blob/master/_autodocs/ctypes-bindings.md

These functions allow setting and getting internal libmagic parameters. They require libmagic version 5.30 or later. The C signatures involve a magic_t cookie, an integer parameter, and a pointer to a size_t value.

```APIDOC
## magic_setparam / magic_getparam

### Description
Allows setting and getting internal libmagic parameters. Requires libmagic version 5.30 or later.

### C Signature
- `int magic_setparam(magic_t cookie, int param, size_t *value)`
- `int magic_getparam(magic_t cookie, int param, size_t *value)`

### Parameters
- `cookie` (magic_t) - The magic library cookie.
- `param` (int) - The parameter to set or get.
- `value` (size_t *) - A pointer to the value to set or to store the retrieved value.
```

--------------------------------

### Use Custom Magic Database

Source: https://github.com/ahupp/python-magic/blob/master/_autodocs/usage-guide.md

Specifies an alternative magic database file to use for detection. If the specified file does not exist, it falls back to using the default magic database.

```python
import magic
import os

# Use alternative magic database
magic_db = '/etc/magic'
if os.path.exists(magic_db):
    m = magic.Magic(magic_file=magic_db)
    result = m.from_file('document.pdf')
else:
    # Fall back to default database
    result = magic.from_file('document.pdf')
```

--------------------------------

### Inspect Compressed Files

Source: https://github.com/ahupp/python-magic/blob/master/_autodocs/INDEX.md

Enable decompression by setting `uncompress=True` when creating a `magic.Magic` instance to inspect contents of compressed files like archives.

```python
m = magic.Magic(uncompress=True)
result = m.from_file('archive.tar.gz')
```

--------------------------------

### Migrate File Object Detection: Old vs New

Source: https://github.com/ahupp/python-magic/blob/master/_autodocs/compat-layer.md

Compares the deprecated `detect_from_fobj` with the recommended `magic.from_descriptor` for detecting MIME type from a file object.

```python
import magic
with open('file.pdf', 'rb') as f:
    result = magic.detect_from_fobj(f)
    mime = result.mime_type
```

```python
import magic
with open('file.pdf', 'rb') as f:
    mime = magic.from_descriptor(f.fileno(), mime=True)
```

--------------------------------

### Get File Extensions with libmagic

Source: https://github.com/ahupp/python-magic/blob/master/_autodocs/usage-guide.md

Retrieves file extensions based on the detected file type using a Magic instance configured with `extension=True`. Note that this feature requires libmagic version 5.24 or later and may raise a `NotImplementedError` on older versions.

```python
import magic

# Get valid extensions (requires libmagic 5.24+)
try:
    m = magic.Magic(extension=True)
    extensions = m.from_file('document.pdf')
    print(extensions)
    # Output: 'pdf/pdf' or similar
except NotImplementedError:
    print("extension detection not supported in this libmagic version")
```

--------------------------------

### Optimize Performance with Reusable Instance

Source: https://github.com/ahupp/python-magic/blob/master/_autodocs/INDEX.md

For performance optimization, reuse a `magic.Magic` instance across multiple file detections instead of calling module functions repeatedly. Instantiate with desired parameters like `mime=True`.

```python
# Reuse instance instead of calling module functions
m = magic.Magic(mime=True)
for file in files:
    mime = m.from_file(file)
```

--------------------------------

### Handle MagicException Errors

Source: https://github.com/ahupp/python-magic/blob/master/_autodocs/usage-guide.md

Demonstrates how to catch and handle MagicException for invalid database paths or detection failures. Also shows handling FileNotFoundError.

```python
import magic

try:
    # Invalid magic database path
    m = magic.Magic(magic_file='/invalid/path/to/magic')
except magic.MagicException as e:
    print(f"Magic error: {e.message}")

try:
    # File not found
    result = magic.from_file('/nonexistent/file.pdf')
except FileNotFoundError as e:
    print(f"File not found: {e}")
except magic.MagicException as e:
    print(f"Detection error: {e.message}")
```

--------------------------------

### Identify File Type from Path

Source: https://github.com/ahupp/python-magic/blob/master/README.md

Use `magic.from_file()` to identify the file type by its path. It's recommended to read at least the first 2048 bytes for accurate identification.

```python
>>> import magic
>>> magic.from_file("testdata/test.pdf")
'PDF document, version 1.2'
```

--------------------------------

### Migrate File Detection: Old vs New

Source: https://github.com/ahupp/python-magic/blob/master/_autodocs/compat-layer.md

Compares the deprecated `detect_from_filename` with the recommended `magic.Magic(mime=True).from_file` for extracting MIME type, encoding, and name.

```python
import magic
result = magic.detect_from_filename('file.pdf')
mime = result.mime_type
encoding = result.encoding
name = result.name
```

```python
import magic
m = magic.Magic(mime=True)
mime = m.from_file('file.pdf')

m_enc = magic.Magic(mime_encoding=True)
encoding = m_enc.from_file('file.pdf')

m_name = magic.Magic()
name = m_name.from_file('file.pdf')
# Or use module-level function
name = magic.from_file('file.pdf')
```

--------------------------------

### magic_load

Source: https://github.com/ahupp/python-magic/blob/master/_autodocs/ctypes-bindings.md

Loads a magic database file. If filename is NULL, loads the default database.

```APIDOC
## magic_load

### Description
Loads a magic database file. If filename is NULL, loads the default database.

### Method
(Not specified, likely a Python function call)

### Parameters
#### Path Parameters
(None specified)

#### Query Parameters
(None specified)

#### Request Body
(None specified)

### Request Example
(Not specified)

### Response
#### Success Response (0)
Returns 0 on success.

#### Response Example
(Not specified)

### Error Handling
Raises `MagicException` if result is -1.
```

--------------------------------

### Configure File Extension Output

Source: https://github.com/ahupp/python-magic/blob/master/_autodocs/configuration.md

Use `extension=True` to retrieve file extensions in a slash-separated format (e.g., 'pdf/pdf'). Requires libmagic 5.24+. Raises `NotImplementedError` for older versions.

```python
import magic

try:
    m = magic.Magic(extension=True)
    extensions = m.from_file('document.pdf')
    print(extensions)
    # Possible output: 'pdf/pdf' or '???'
except NotImplementedError:
    print("MAGIC_EXTENSION not supported in this libmagic version")
```

--------------------------------

### Detect File Type from URL with Urllib

Source: https://github.com/ahupp/python-magic/blob/master/_autodocs/usage-guide.md

Illustrates downloading a file from a URL using `urllib.request` and detecting its MIME type using `magic.from_buffer`.

```python
import magic
import urllib.request

# Download file and detect type
url = 'https://example.com/document.pdf'
with urllib.request.urlopen(url) as response:
    # Read into buffer
    data = response.read()
    
    # Detect MIME type
    mime_type = magic.from_buffer(data, mime=True)
    print(f"Downloaded file type: {mime_type}")
```

--------------------------------

### Test libmagic Loading and Functionality

Source: https://github.com/ahupp/python-magic/blob/master/_autodocs/loader-module.md

Provides simple tests to verify if libmagic has been loaded, to retrieve its version, and to perform a basic file type detection using from_buffer.

```python
# Simple test
import magic
print(f"libmagic loaded: {magic.libmagic}")

# Test version
try:
    version = magic.version()
    print(f"libmagic version: {version}")
except NotImplementedError:
    print("magic_version not supported")

# Test basic functionality
result = magic.from_buffer(b'test')
print(f"Detection test: {result}")
```

--------------------------------

### Exceptions and Constants

Source: https://github.com/ahupp/python-magic/blob/master/_autodocs/INDEX.md

Details the exceptions that can be raised by the library and the available constants for controlling output formats and behavior.

```APIDOC
## Exceptions and Constants

### Description
Information on handling exceptions and using predefined constants for customization.

### Exceptions

#### `magic.MagicException`
Custom exception raised for errors during magic operations. Access the error message via the `message` attribute.

### Constants

#### Output Formats
- `magic.MAGIC_MIME_TYPE`: Get MIME type.
- `magic.MAGIC_MIME_ENCODING`: Get character encoding.
- `magic.MAGIC_EXTENSION`: Get file extensions.

#### Behavior Flags
- `magic.MAGIC_COMPRESS`: Look inside compressed files.
- `magic.MAGIC_CONTINUE`: Return all matches.
- `magic.MAGIC_SYMLINK`: Follow symlinks.
- `magic.MAGIC_RAW`: Do not decode non-printable characters.

#### Disable Checks
- `magic.MAGIC_NO_CHECK_ELF`: Skip ELF detection.
- `magic.MAGIC_NO_CHECK_TEXT`: Skip text detection.
- `magic.MAGIC_NO_CHECK_TAR`: Skip tar detection.
- ... (many more check flags available)
```

--------------------------------

### magic_compile

Source: https://github.com/ahupp/python-magic/blob/master/_autodocs/ctypes-bindings.md

Compiles a magic database file. Creates a .mgc compiled version.

```APIDOC
## magic_compile

### Description
Compiles a magic database file. Creates a .mgc compiled version.

### Method
(Not specified, likely a Python function call)

### Parameters
#### Path Parameters
(None specified)

#### Query Parameters
(None specified)

#### Request Body
(None specified)

### Request Example
(Not specified)

### Response
#### Success Response (0)
Returns 0 on success.

#### Response Example
(Not specified)

### Error Handling
(Not specified)
```

--------------------------------

### Handle MagicException During File Detection

Source: https://github.com/ahupp/python-magic/blob/master/_autodocs/exceptions.md

Shows how to catch MagicException when calling `from_file` if libmagic fails to process the file.

```python
# Catching errors during file detection
try:
    result = magic.from_file('document.pdf')
except magic.MagicException as e:
    print(f"Detection failed: {e.message}")
```

--------------------------------

### Configure Uncompressing Files with Python-Magic

Source: https://github.com/ahupp/python-magic/blob/master/_autodocs/configuration.md

Set `uncompress=True` to decompress and identify the contents of compressed files, or `False` to report the compression format itself. This works for various archive formats and can be used with MIME type detection.

```python
import magic

# Without uncompress
m = magic.Magic(uncompress=False)
result = m.from_file('archive.tar.gz')
# Output: 'gzip compressed data, from Unix'

# With uncompress
m = magic.Magic(uncompress=True)
result = m.from_file('archive.tar.gz')
# Output: 'POSIX tar archive'

# Also works with MIME type
m_mime = magic.Magic(mime=True, uncompress=True)
result = m_mime.from_file('archive.tar.gz')
# Output: 'application/x-tar'
```

--------------------------------

### Output Format Constants

Source: https://github.com/ahupp/python-magic/blob/master/_autodocs/INDEX.md

Use constants like MAGIC_MIME_TYPE, MAGIC_MIME_ENCODING, and MAGIC_EXTENSION to specify output formats.

```python
# Output formats
magic.MAGIC_MIME_TYPE          # Get MIME type
magic.MAGIC_MIME_ENCODING      # Get character encoding
magic.MAGIC_EXTENSION          # Get file extensions
```

--------------------------------

### Generate Library Loading Candidates

Source: https://github.com/ahupp/python-magic/blob/master/_autodocs/loader-module.md

Generates a list of candidate library names and paths to try loading for the current platform. This is used internally by load_lib() to find the libmagic library.

```python
from magic import loader

# Generate candidates for current platform
for candidate in loader._lib_candidates():
    if candidate:
        print(f"Trying to load: {candidate}")
```

--------------------------------

### Specify Custom Magic Database File

Source: https://github.com/ahupp/python-magic/blob/master/_autodocs/configuration.md

Use this snippet to specify a custom magic database file for file type detection. It includes a fallback to the system default if the custom file is not found.

```python
import magic
import os

# Use custom magic database
custom_db = '/opt/custom/magic'
if os.path.exists(custom_db):
    m = magic.Magic(magic_file=custom_db)
    result = m.from_file('document.pdf')
else:
    # Fall back to default
    m = magic.Magic()
    result = m.from_file('document.pdf')
```

--------------------------------

### Web Server Content-Type Detection

Source: https://github.com/ahupp/python-magic/blob/master/_autodocs/configuration.md

Configure Magic for fast MIME type detection suitable for web serving. Disables ELF and text file checks for performance. Ensure the 'static/document.pdf' file exists.

```python
import magic

# Fast MIME type detection for web serving
m = magic.Magic(
    mime=True,
    check_elf=False,
    check_text=False,
)

mime_type = m.from_file('static/document.pdf')
# Returns: 'application/pdf'
```

--------------------------------

### Handling Exceptions with Per-Thread Magic Instances (Recommended)

Source: https://github.com/ahupp/python-magic/blob/master/_autodocs/exceptions.md

This snippet shows the recommended approach for thread safety: each thread creates its own Magic instance. This avoids race conditions and ensures proper exception handling for MagicException.

```python
# RECOMMENDED: each thread creates its own instance
def worker(filename):
    m = magic.Magic()  # Create per-thread instance
    try:
        result = m.from_file(filename)
    except magic.MagicException as e:
        print(f"Error: {e.message}")

threads = [threading.Thread(target=worker, args=(f,)) for f in files]
for t in threads:
    t.start()
```