Metadata-Version: 2.4
Name: popoto
Version: 1.6.1
Summary: A Python Redis ORM
Home-page: https://github.com/tomcounsell/popoto
Author: Tom Counsell
Author-email: Tom Counsell <other@tomcounsell.com>
License: MIT License
        
        Copyright (c) 2022 Tom Counsell
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/tomcounsell/popoto
Project-URL: Documentation, https://popoto.io/
Project-URL: Bug_Tracker, https://github.com/tomcounsell/popoto/issues
Keywords: redis,ORM,database
Classifier: Development Status :: 5 - Production/Stable
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: redis>=4.4.4
Requires-Dist: msgpack>=1.0.4
Provides-Extra: dataframe
Requires-Dist: pandas>=1.4.3; extra == "dataframe"
Requires-Dist: numpy>=1.23.1; extra == "dataframe"
Requires-Dist: msgpack-numpy>=0.4.8; extra == "dataframe"
Provides-Extra: ulid
Requires-Dist: ulid-py>=1.1.0; extra == "ulid"
Provides-Extra: ksuid
Requires-Dist: cyksuid>=1.0.0; extra == "ksuid"
Provides-Extra: embeddings
Requires-Dist: numpy>=1.23.1; extra == "embeddings"
Provides-Extra: voyage
Requires-Dist: voyageai>=0.3.0; extra == "voyage"
Requires-Dist: numpy>=1.23.1; extra == "voyage"
Provides-Extra: openai
Requires-Dist: openai>=1.0.0; extra == "openai"
Requires-Dist: numpy>=1.23.1; extra == "openai"
Provides-Extra: monitoring
Requires-Dist: sentry-sdk>=2.0.0; extra == "monitoring"
Provides-Extra: dev
Requires-Dist: pytest>=7.1.2; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: mypy>=0.971; extra == "dev"
Requires-Dist: black>=26.3.1; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: mkdocs>=1.6; extra == "docs"
Requires-Dist: mkdocs-material>=9.5; extra == "docs"
Requires-Dist: mkdocstrings[python]>=0.25; extra == "docs"
Requires-Dist: griffe>=0.45; extra == "docs"
Requires-Dist: mkdocs-gen-files>=0.5; extra == "docs"
Requires-Dist: mkdocs-literate-nav>=0.6; extra == "docs"
Requires-Dist: mkdocs-open-in-new-tab>=1.0; extra == "docs"
Dynamic: license-file

### Status
[![pypi package](https://badge.fury.io/py/popoto.svg)](https://pypi.org/project/popoto)
[![total downloads](https://pepy.tech/badge/popoto)](https://pepy.tech/project/popoto)
[![deploy docs](https://github.com/tomcounsell/popoto/actions/workflows/deploy-docs.yml/badge.svg)](https://github.com/tomcounsell/popoto/actions/workflows/deploy-docs.yml)

### Documentation: [**popoto.io**](https://popoto.io/)


# Popoto - A Redis/Valkey ORM (Object-Relational Mapper)

## Install

```
pip install popoto
```

## Basic Usage

``` python
from popoto import Model, KeyField, Field, SortedField

class Restaurant(Model):
    name = KeyField()
    cuisine = Field()
    rating = SortedField(type=float)

Restaurant.create(name="Burger Palace", cuisine="American", rating=4.5)

restaurant = Restaurant.query.get(name="Burger Palace")

print(f"{restaurant.name} serves {restaurant.cuisine} food.")
# => "Burger Palace serves American food."
```

### **Popoto** Features

 - very fast stores and queries
 - familiar syntax, similar to Django models
 - Async operations for asyncio-based applications
 - Geometric distance search
 - Timeseries for streaming data
 - compatible with Pandas, Xarray for N-dimensional matrix search
 - PubSub for message queues, streaming data processing
 - **Full Redis and Valkey support** - works with both out of the box
 - **[Agent Memory](docs/guides/agent-memory-quickstart.md)** - programmable memory primitives for AI agents (decay, confidence, associations, context assembly)
 - **[Content & Embeddings](docs/features/content-and-embedding-fields.md)** - large content storage, vector embeddings, and semantic search

**Popoto** is ideal for streaming data. The pub/sub module allows you to trigger state updates in real time.
Currently being used in production for:

 - trigger buy/sell actions from streaming price data
 - robots sending each other messages for teamwork
 - compressing sensor data and training neural networks


## Advanced Usage

``` python
import popoto
from popoto import Relationship, DatetimeField

class Restaurant(popoto.Model):
    name = popoto.KeyField()
    cuisine = popoto.Field()
    rating = popoto.SortedField(type=float)
    location = popoto.GeoField()

class Order(popoto.Model):
    order_id = popoto.AutoKeyField()
    restaurant = Relationship(Restaurant)
    total = popoto.SortedField(type=float)
    status = popoto.Field(default="pending")
    created_at = DatetimeField(auto_now_add=True)

    class Meta:
        order_by = "-created_at"
        ttl = 2592000  # 30 days
```


## Save Instances

``` python
restaurant = Restaurant(name="Burger Palace")
restaurant.cuisine = "American"
restaurant.rating = 4.5
restaurant.location = (40.7128, -74.0060)
restaurant.save()

order = Order.create(restaurant=restaurant, total=24.99)
```


## Queries

``` python
from datetime import datetime, timedelta

midtown = (40.7549, -73.9840)
yesterday = datetime.now() - timedelta(days=1)

nearby_restaurants = Restaurant.query.filter(
    location=midtown,
    location_radius=5, location_radius_unit='km',
    rating__gte=4.0
)

print(len(nearby_restaurants))
# => 1

recent_orders = Order.query.filter(
    created_at__gte=yesterday,
    total__gte=10.00
)
```


# Documentation

Documentation is available at [**popoto.io**](https://popoto.io/)

Please create new feature and documentation related issues [github.com/tomcounsell/popoto/issues](https://github.com/tomcounsell/popoto/issues) or make a pull request with your improvements.


# License

Popoto ORM is released under the MIT Open Source license.


# Popoto Community

Questions, bug reports, and feature requests are welcome on [GitHub Issues](https://github.com/tomcounsell/popoto/issues) and [GitHub Discussions](https://github.com/tomcounsell/popoto/discussions). Contributions via pull request are encouraged.

![](/static/popoto.png)

Popoto gets its name from the [Maui dolphin](https://en.wikipedia.org/wiki/M%C4%81ui_dolphin) subspecies - the world's smallest dolphin subspecies.
Because dolphins are fast moving, agile, and work together in social groups. In the same way, Popoto wraps Redis and Valkey to make it easy to manage streaming timeseries data and object persistence.
