# File Level

A command-line tool for renaming file level suffixes to classify documents by security levels and organizational categories.

## Features

- **Security Classification**: Add/remove document security levels (Public, Normal, Internal, Confidential, Classified)
- **Batch Processing**: Process multiple files simultaneously with parallel execution
- **Intelligent Marking**: Automatically adds appropriate bracket styles around level indicators
- **Conflict Resolution**: Handles filename conflicts by appending unique identifiers
- **Validation**: Comprehensive file existence and permission checking
- **Cross-platform**: Works on Windows, macOS, and Linux

## Security Levels

The tool supports 5 security levels:

| Level | Code | Description          | Markers        |
| ----- | ---- | -------------------- | -------------- |
| 0     | -    | Clear level (remove) | (None)         |
| 1     | PUB  | Public               | (PUB) or (NOR) |
| 2     | INT  | Internal             | (INT)          |
| 3     | CON  | Confidential         | (CON)          |
| 4     | CLA  | Classified           | (CLA)          |

## Installation

```bash
# Install via pip
pip install -e .

# Or install in development mode
uv pip install -e .
```

## Usage

### Command Line Interface

```bash
# Basic usage - add level 2 (Internal) to files
filelevel document1.pdf document2.docx --level 2

# Short form command
filelvl *.txt --level 3

# Clear existing levels (level 0)
filelevel confidential.doc --level 0

# Process multiple files with different extensions
filelevel report.pdf presentation.pptx spreadsheet.xlsx --level 1
```

### Examples

```bash
# Add Confidential level to all PDF files
filelevel *.pdf --level 3

# Batch process documents in a directory
filelevel /path/to/documents/* --level 2

# Clear security markings from sensitive files
filelevel secret_document.txt --level 0

# Process files with spaces in names (use quotes)
filelevel "My Document.pdf" "Report 2024.docx" --level 4
```

## How It Works

1. **Level Detection**: Identifies existing level markers in filenames
2. **Marker Removal**: Removes all existing level and numeric markers
3. **Level Addition**: Adds the specified level marker with appropriate brackets
4. **Conflict Handling**: Resolves naming conflicts by appending UUIDs
5. **Parallel Processing**: Processes multiple files concurrently for efficiency

### Filename Transformation Examples

```bash
Original: report.pdf
Level 2:  report(INT).pdf

Original: document(CON).txt  
Level 1:  document(PUB).txt

Original: secret(CLA).docx
Level 0:  secret.docx

Original: file123.txt
Level 3:  file(CON).txt  # removes numeric markers too
```

## Configuration

The tool uses the following default configuration:

```python
LEVELS = {
    "0": "",           # Clear level
    "1": "PUB,NOR",    # Public/Normal
    "2": "INT",        # Internal
    "3": "CON",        # Confidential
    "4": "CLA",        # Classified
}

BRACKETS = [" ([_（【-", " )]_）】"]  # Valid bracket characters
MARK_BRACKETS = ["(", ")"]           # Default brackets for markers
```

## Performance

- **Parallel Processing**: Uses ThreadPoolExecutor with 8 workers by default
- **Efficient**: Minimal I/O operations, fast string processing
- **Memory Safe**: Processes files one at a time in memory-constrained environments

## Error Handling

The tool provides comprehensive error handling:

- **File Validation**: Checks file existence and permissions
- **Level Validation**: Ensures level is between 0-4
- **Conflict Resolution**: Automatic handling of duplicate filenames
- **Graceful Degradation**: Continues processing valid files even if some fail

## Development

### Running Tests

```bash
# Run unit tests
pytest pytola/filelevel/tests/

# Run with coverage
pytest --cov=pytola.filelevel pytola/filelevel/tests/
```

### Code Structure

```bash
pytola/filelevel/
├── filelevel.py     # Main implementation
├── tests/           # Test files
│   ├── test_filelevel.py      # Unit tests
│   └── test_benchmark.py      # Performance benchmarks
├── README.md        # This documentation
└── pyproject.toml   # Package configuration
```

## Contributing

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all tests pass
5. Submit a pull request

## License

This project is part of the pytola toolkit and follows the same licensing terms.

## See Also

- [pytola](https://github.com/your-org/pytola) - Main toolkit repository
- [docscan](../docscan/) - Document scanning and analysis
- [filedate](../filedate/) - File date management
- [pdfcrypt](../pdfcrypt/) - PDF encryption tools
