Metadata-Version: 2.4
Name: oligo-emojis
Version: 0.1.0
Summary: Oligo-emojis — a mini, dependency-free emoji helper library (author: OligoTech)
Author: OligoTech
License: MIT
Keywords: emoji,emojis,oligo
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: full
Requires-Dist: emoji>=2.0; extra == "full"
Dynamic: license-file

# OLIGO-EMOJIS

Oligo-emojis is a lightweight, fun Python emoji utility library.

Author: OligoTech

This package provides categorized emoji lists and convenient helpers to retrieve and sample emojis for use in demos, tests, command-line fun, or UI placeholders.

## Quick demo

```python
from oligoemojis import Emojis

e = Emojis()
print(e.list_categories())
print(e.get('Smileys', 3))
print(e.random())
print(e.random('Animals', 4))
```

## API reference

Class: `Emojis(default_count: int = 1)`

- `list_categories()` -> List[str]
	- Returns a sorted list of available categories.

- `get(category: str, q: Union[int, str] = None)` -> List[str] | str
	- Returns emojis from the named category. `q` can be an int (number of items), `'all'` to get the whole list, or omitted to use the instance default.
	- Category matching is case-insensitive.

- `random(category: Optional[str] = None, q: int = 1)` -> str | List[str]
	- Returns a random emoji (when `q==1`) or a list of `q` random emojis. If `category` is `None`, a random category is selected.
	- If `q > size_of_category`, sampling is done with replacement to satisfy the count.

Compatibility helpers (keeps older API names):

- `smileys(q=None)` — returns first `q` smileys or `'all'` for all smileys.
- `smileys_random()` — returns a single random smiley.

## Categories included

Smileys, People, Animals, Foods, Drinks, Activities, Travel, Places, Objects, Symbols, Flags

## Notes

- The library is intentionally simple and dependency-free.
- It is safe to call `random` or `get` with small counts; invalid categories return a helpful message.

If you want additional emoji sets or suggestions, open an issue or submit a PR.
