Metadata-Version: 2.1
Name: macos-tags
Version: 1.2.0
Summary: A python libraty for working with macOS tags
Home-page: https://github.com/dmkskn/macos-tags
License: MIT
Keywords: macos,tags
Author: Dima Koskin
Author-email: dmksknn@gmail.com
Requires-Python: >=3.6,<4.0
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Dist: mdfind (>=2019.4.13,<2020.0.0)
Requires-Dist: xattr (>=0.9.7,<0.10.0)
Project-URL: Repository, https://github.com/dmkskn/macos-tags
Description-Content-Type: text/markdown

# `macos-tags`

A python library for working with macOS tags.

## Installation

```bash
pip install macos-tags
```

## Tutorial & Usage

Get files by tag name:

```python
>>> import macos_tags

>>> macos_tags.find("design")
['/Users/home/apple.jpg', '/Users/home/WEB_POSTERS.png']
```

Count files by tag name:

```python
>>> macos_tags.count("design")
2
```

List the tags on the file:

```python
>>> path = "/path/to/file"

>>> macos_tags.get_all(path)
[Tag(name='design', color=None), Tag(name='python', color=<Color.GREEN: 2>]
```

Add a tag to file:

```python
>>> macos_tags.add("design", file=path)
```

> When using `str` objects to define a tag, if a tag does not exist in the system, it will be added without a color label.

Add a new color tag by using `Tag` data class and `Color` enumeration:

```python
>>> from macos_tags import Tag, Color


>>> tag = Tag(name="python", color=Color.GREEN)

>>> macos_tags.add(tag, file=path)
```

Add a new color tag using the `str` object, where the tag name and color number (from 1 to 7) are separated by the literal `\n`:

```python
>>> tag = f"python\n{Color.GREEN}"  # == "python\n2"

>>> macos_tags.add(tag, file=path)
```

> If the tag already exists in the system with a different color, the new color will be ignored.

Remove tag from file:

```python
>>> macos_tags.remove(tag, file=path)
```

Remove all tags from a file at once:

```python
>>> macos_tags.remove_all(path)
```

Change all tags in the file:

```python
>>> macos_tags.get_all(path)
[Tag(name='design', color=None), Tag(name='python', color=<Color.GREEN: 2>]

>>> new_tags = [Tag("book"), Tag("programming", Color.BLUE)]

>>> macos_tags.set_all(new_tags, file=path)

>>> macos_tags.get_all(path)
[Tag(name="book", color=None), Tag("programming", <Color.BLUE: 4>]
```
