Metadata-Version: 2.4
Name: pywinselect
Version: 0.2.1
Summary: Get selected files and folders in Windows
Project-URL: Homepage, https://github.com/offerrall/pywinselect
Project-URL: Repository, https://github.com/offerrall/pywinselect
Project-URL: Issues, https://github.com/offerrall/pywinselect/issues
Author: Beltrán Offerrall
License-Expression: MIT
License-File: LICENSE
Keywords: automation,files,selection,streamdeck,windows
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: pywin32
Provides-Extra: dev
Requires-Dist: build; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Description-Content-Type: text/markdown

# pywinselect

[![PyPI version](https://img.shields.io/pypi/v/pywinselect.svg)](https://pypi.org/project/pywinselect/)
[![Python versions](https://img.shields.io/pypi/pyversions/pywinselect.svg)](https://pypi.org/project/pywinselect/)
[![License: MIT](https://img.shields.io/pypi/l/pywinselect.svg)](https://github.com/offerrall/pywinselect/blob/main/LICENSE)

Get selected files and folders in Windows.

## Installation

```bash
pip install pywinselect
```

## What it does

`pywinselect` detects which files or folders you have selected in Windows, regardless of where they are.

It works in:
- **File Explorer** - Any open Explorer window
- **Desktop** - Files and folders selected on your desktop

Returns absolute paths to everything selected. If nothing is selected, returns an empty list.

## Why use it

When building automation tools, you often need to know what the user has selected. Without this library, you'd have to:

- Write 100+ lines of win32 API code
- Handle File Explorer and Desktop separately  
- Deal with clipboard backup/restore
- Debug why it doesn't work on Desktop

`pywinselect` solves this in one line.

## Use cases

- **Stream Deck scripts** - Create buttons that act on selected files
- **Keyboard macros** - Automate repetitive file operations
- **Custom context menus** - Build tools that work with selections
- **Productivity apps** - Quick actions on currently selected items
- **Batch processing** - Process whatever the user has selected

## Usage
```python
from pywinselect import get_selected

# Get all selected items (Desktop + Explorer)
files = get_selected()

# Filter by type
only_files = get_selected(filter_type="files")
only_folders = get_selected(filter_type="folders")

# Get selection from specific location
desktop_only = get_selected(only_desktop=True)
explorer_only = get_selected(only_explorer=True)
```

## API

### `get_selected(filter_type=None, only_desktop=False, only_explorer=False) -> list[str]`

Returns list of absolute paths to selected items.

**Parameters:**
- `filter_type` (optional): Filter results by type
  - `None` - Return both files and folders (default)
  - `"files"` - Return only files
  - `"folders"` - Return only folders
- `only_desktop` (optional): If `True`, only get selection from Desktop
- `only_explorer` (optional): If `True`, only get selection from File Explorer

**Returns:** 
- `list[str]` - Paths to selected files/folders
- `[]` - Empty list if nothing is selected

**Raises:**
- `ValueError` - If both `only_desktop` and `only_explorer` are `True`

**Examples:**
```python
>>> get_selected()
['C:\\Users\\John\\file.txt', 'C:\\Users\\John\\Documents']

>>> get_selected(filter_type="files")
['C:\\Users\\John\\file.txt']

>>> get_selected(filter_type="folders")
['C:\\Users\\John\\Documents']

>>> get_selected(only_desktop=True)
['C:\\Users\\John\\Desktop\\file.txt']

>>> get_selected(only_explorer=True)
['C:\\Users\\John\\Downloads\\file.txt']

>>> get_selected(only_desktop=True, only_explorer=True)
ValueError: Cannot set both only_desktop and only_explorer to True
```

## How it works

Uses official Windows Shell COM APIs (`IShellView`, `IDataObject`) - the same interfaces Windows Explorer uses internally. 

**Safe by design:**
- Read-only operations
- No keyboard simulation
- No clipboard modifications
- No system state changes

## Requirements

- Python 3.10+
- Windows
- pywin32

## License

MIT