kover 2.7.2__tar.gz → 2.7.3__tar.gz

kover-2.7.3/PKG-INFO

@@ -0,0 +1,239 @@
+Metadata-Version: 2.4
+Name: kover
+Version: 2.7.3
+Summary: Fully async mongodb driver for mongod and replica sets.
+Project-URL: Repository, https://github.com/megawattka/kover
+Project-URL: Documentation, https://github.com/megawattka/kover
+Author-email: megawattka <gunter56741@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: async driver,kover,kover mongodb,mongo async,mongod driver,mongodb
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: dnspython>=2.7.0
+Requires-Dist: pydantic>=2.10.6
+Requires-Dist: typing-extensions>=4.12.2
+Provides-Extra: snappy
+Requires-Dist: python-snappy; extra == 'snappy'
+Provides-Extra: zstd
+Requires-Dist: zstd; extra == 'zstd'
+Description-Content-Type: text/markdown
+
+# kover
+![Build Status](https://img.shields.io/github/actions/workflow/status/megawattka/kover/actions.yml)
+![License](https://img.shields.io/github/license/megawattka/kover)
+![Python - Req](https://img.shields.io/badge/python-3.10+-blue)
+![Pypi Status](https://img.shields.io/pypi/status/kover)
+![Last Commit](https://img.shields.io/github/last-commit/megawattka/kover)
+![MongoDB](https://img.shields.io/badge/MongoDB-6.0+-green)
+
+Kover is a model-oriented, strictly-typed, and asynchronous Object-Document Mapper (ODM) for MongoDB. It was built from the ground up using `asyncio` to provide a clean and high-performance alternative to traditional database drivers that rely on thread pools.
+
+This library is inspired by `aiomongo` but is modernized for recent versions of Python and MongoDB, with a strong emphasis on type safety and developer experience. Kover is linted with Ruff and supports `pyright`'s strict type-checking mode.
+
+## Features
+
+*   **Fully Asynchronous:** Uses `asyncio` for non-blocking database operations, avoiding the use of thread pool executors.
+*   **Pydantic Integration:** Define your document schemas using Pydantic-style models for automatic validation and serialization.
+*   **Strictly Typed:** Designed for modern Python, with full type hinting support for better static analysis and code completion.
+*   **Modern MongoDB Support:** Built for MongoDB 6.0+ and omits deprecated features for a cleaner API.
+*   **Comprehensive API:** Supports nearly all of PyMongo's features, including CRUD operations, bulk writes, transactions, and GridFS.
+*   **Authentication:** Supports all standard MongoDB authentication mechanisms.
+
+**Note:** The `kover.bson` package is adapted from the `pymongo` source code.
+
+## Dependencies
+- `Python 3.10+`
+- `pydantic>=2.10.6`
+- `dnspython>=2.7.0`
+
+## Installation
+
+```bash
+pip install kover
+```
+Optional dependencies for compression can be installed with:
+```bash
+pip install kover[snappy,zstd]
+```
+
+## Quick Start
+
+Connect to MongoDB, create a client, and perform a simple query.
+
+```python
+import asyncio
+import logging
+
+from kover import Kover
+
+log = logging.getLogger(__name__)
+logging.basicConfig(level=logging.INFO)
+
+async def main():
+    # Connect using a connection string
+    client = await Kover.from_uri("mongodb://user:pass@host:port/?tls=false")
+    
+    # Or, create a client programmatically
+    # from kover import AuthCredentials
+    # credentials = AuthCredentials(username="<user>", password="<pass>")
+    # client = await Kover.make_client(credentials=credentials)
+
+    db = client.testdb
+    collection = db.test_collection
+
+    # Insert a document
+    await collection.insert_one({"message": "Hello, Kover!"})
+
+    # Find documents
+    found = await collection.find().to_list()
+    log.info(found)
+
+    await client.close()
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+## Examples
+
+### Defining Schemas with Pydantic
+
+Kover leverages Pydantic for defining document structures. This provides data validation, serialization, and a clear, explicit schema.
+
+```python
+from uuid import UUID
+from kover import Document
+
+class User(Document):
+    """A user document schema."""
+
+    uuid: UUID
+    name: str
+    age: int
+```
+
+You can even generate and enforce a JSON schema on the collection in MongoDB.
+
+```python
+from kover import SchemaGenerator
+
+# Generate a schema from the User model
+schema = client.generate_schema(User)
+
+# Apply the schema to the collection
+collection = await client.db.users.create_if_not_exists()
+await collection.set_validator(schema)
+```
+
+### Inserting Documents
+
+You can insert Pydantic model instances directly into a collection.
+
+```python
+from uuid import uuid4
+
+user = User(name="Jane Doe", age=30, uuid=uuid4())
+result = await client.db.users.insert_one(user)
+log.info("Inserted user with ID: %s", result)
+```
+
+### Querying Documents
+
+Kover's cursor provides a powerful and flexible way to retrieve data.
+
+**Iterating over a Cursor:**
+```python
+# The cursor asynchronously yields `User` objects
+async with client.db.users.find(cls=User).limit(100) as cursor:
+    async for user in cursor:
+        log.info("User: %s, Age: %d", user.name, user.age)
+```
+
+**Fetching all results into a list:**
+```python
+users_list = await client.db.users.find(cls=User).to_list()
+```
+
+### Updating and Deleting
+
+Use `Update` and `Delete` models to construct operations. This approach makes it clear which documents are being targeted and what modifications are being made.
+
+```python
+from kover import Update, Delete
+
+# Update a user's age
+update = Update({"name": "Jane Doe"}, {"$set": {"age": 31}})
+await client.db.users.update(update)
+
+# Delete a user
+delete = Delete({"name": "Jane Doe"}, limit=1)
+n_deleted = await client.db.users.delete(delete)
+log.info("Documents deleted: %d", n_deleted)
+```
+
+### Bulk Writes
+
+Perform multiple operations in a single request for efficiency.
+
+```python
+from kover import BulkWriteBuilder, Update, Delete
+
+builder = BulkWriteBuilder()
+builder.add_insert([{"product": "A"}], ns="testdb.inventory")
+builder.add_update(
+    Update({"product": "A"}, {"$set": {"quantity": 10}}),
+    ns="testdb.inventory",
+)
+builder.add_delete(Delete({"product": "A"}, limit=1), ns="testdb.inventory")
+
+await client.bulk_write(builder.build())
+```
+
+### Transactions
+
+Kover supports ACID transactions for operations that require atomicity.
+
+```python
+session = await client.start_session()
+collection = client.db.test
+
+async with session.start_transaction() as transaction:
+    await collection.insert_one({"step": 1}, transaction=transaction)
+    await collection.insert_one({"step": 2}, transaction=transaction)
+    # The transaction will be automatically committed on successful exit.
+    # If an exception occurs, it will be aborted.
+```
+
+### GridFS for Large Files
+
+Store and retrieve large files (e.g., images, videos) seamlessly with GridFS.
+
+```python
+from kover.gridfs import GridFS
+
+# Get a GridFS instance for a database
+fs = await GridFS(client.get_database("files")).indexed()
+
+# Put a file into GridFS
+file_id = await fs.put(b"Hello, large world!", filename="greeting.txt")
+
+# Retrieve the file
+file_info, file_bytes_io = await fs.get_by_file_id(file_id)
+
+log.info(file_info)
+log.info(file_bytes_io.read())
+```
+
+## Found a Bug?
+
+If you find a bug, please [open an issue](https://github.com/megawattka/kover/issues). Better yet, create a pull request with a fix. Contributions are welcome! ❤️

kover-2.7.3/README.md

@@ -0,0 +1,209 @@
+# kover
+![Build Status](https://img.shields.io/github/actions/workflow/status/megawattka/kover/actions.yml)
+![License](https://img.shields.io/github/license/megawattka/kover)
+![Python - Req](https://img.shields.io/badge/python-3.10+-blue)
+![Pypi Status](https://img.shields.io/pypi/status/kover)
+![Last Commit](https://img.shields.io/github/last-commit/megawattka/kover)
+![MongoDB](https://img.shields.io/badge/MongoDB-6.0+-green)
+
+Kover is a model-oriented, strictly-typed, and asynchronous Object-Document Mapper (ODM) for MongoDB. It was built from the ground up using `asyncio` to provide a clean and high-performance alternative to traditional database drivers that rely on thread pools.
+
+This library is inspired by `aiomongo` but is modernized for recent versions of Python and MongoDB, with a strong emphasis on type safety and developer experience. Kover is linted with Ruff and supports `pyright`'s strict type-checking mode.
+
+## Features
+
+*   **Fully Asynchronous:** Uses `asyncio` for non-blocking database operations, avoiding the use of thread pool executors.
+*   **Pydantic Integration:** Define your document schemas using Pydantic-style models for automatic validation and serialization.
+*   **Strictly Typed:** Designed for modern Python, with full type hinting support for better static analysis and code completion.
+*   **Modern MongoDB Support:** Built for MongoDB 6.0+ and omits deprecated features for a cleaner API.
+*   **Comprehensive API:** Supports nearly all of PyMongo's features, including CRUD operations, bulk writes, transactions, and GridFS.
+*   **Authentication:** Supports all standard MongoDB authentication mechanisms.
+
+**Note:** The `kover.bson` package is adapted from the `pymongo` source code.
+
+## Dependencies
+- `Python 3.10+`
+- `pydantic>=2.10.6`
+- `dnspython>=2.7.0`
+
+## Installation
+
+```bash
+pip install kover
+```
+Optional dependencies for compression can be installed with:
+```bash
+pip install kover[snappy,zstd]
+```
+
+## Quick Start
+
+Connect to MongoDB, create a client, and perform a simple query.
+
+```python
+import asyncio
+import logging
+
+from kover import Kover
+
+log = logging.getLogger(__name__)
+logging.basicConfig(level=logging.INFO)
+
+async def main():
+    # Connect using a connection string
+    client = await Kover.from_uri("mongodb://user:pass@host:port/?tls=false")
+    
+    # Or, create a client programmatically
+    # from kover import AuthCredentials
+    # credentials = AuthCredentials(username="<user>", password="<pass>")
+    # client = await Kover.make_client(credentials=credentials)
+
+    db = client.testdb
+    collection = db.test_collection
+
+    # Insert a document
+    await collection.insert_one({"message": "Hello, Kover!"})
+
+    # Find documents
+    found = await collection.find().to_list()
+    log.info(found)
+
+    await client.close()
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+## Examples
+
+### Defining Schemas with Pydantic
+
+Kover leverages Pydantic for defining document structures. This provides data validation, serialization, and a clear, explicit schema.
+
+```python
+from uuid import UUID
+from kover import Document
+
+class User(Document):
+    """A user document schema."""
+
+    uuid: UUID
+    name: str
+    age: int
+```
+
+You can even generate and enforce a JSON schema on the collection in MongoDB.
+
+```python
+from kover import SchemaGenerator
+
+# Generate a schema from the User model
+schema = client.generate_schema(User)
+
+# Apply the schema to the collection
+collection = await client.db.users.create_if_not_exists()
+await collection.set_validator(schema)
+```
+
+### Inserting Documents
+
+You can insert Pydantic model instances directly into a collection.
+
+```python
+from uuid import uuid4
+
+user = User(name="Jane Doe", age=30, uuid=uuid4())
+result = await client.db.users.insert_one(user)
+log.info("Inserted user with ID: %s", result)
+```
+
+### Querying Documents
+
+Kover's cursor provides a powerful and flexible way to retrieve data.
+
+**Iterating over a Cursor:**
+```python
+# The cursor asynchronously yields `User` objects
+async with client.db.users.find(cls=User).limit(100) as cursor:
+    async for user in cursor:
+        log.info("User: %s, Age: %d", user.name, user.age)
+```
+
+**Fetching all results into a list:**
+```python
+users_list = await client.db.users.find(cls=User).to_list()
+```
+
+### Updating and Deleting
+
+Use `Update` and `Delete` models to construct operations. This approach makes it clear which documents are being targeted and what modifications are being made.
+
+```python
+from kover import Update, Delete
+
+# Update a user's age
+update = Update({"name": "Jane Doe"}, {"$set": {"age": 31}})
+await client.db.users.update(update)
+
+# Delete a user
+delete = Delete({"name": "Jane Doe"}, limit=1)
+n_deleted = await client.db.users.delete(delete)
+log.info("Documents deleted: %d", n_deleted)
+```
+
+### Bulk Writes
+
+Perform multiple operations in a single request for efficiency.
+
+```python
+from kover import BulkWriteBuilder, Update, Delete
+
+builder = BulkWriteBuilder()
+builder.add_insert([{"product": "A"}], ns="testdb.inventory")
+builder.add_update(
+    Update({"product": "A"}, {"$set": {"quantity": 10}}),
+    ns="testdb.inventory",
+)
+builder.add_delete(Delete({"product": "A"}, limit=1), ns="testdb.inventory")
+
+await client.bulk_write(builder.build())
+```
+
+### Transactions
+
+Kover supports ACID transactions for operations that require atomicity.
+
+```python
+session = await client.start_session()
+collection = client.db.test
+
+async with session.start_transaction() as transaction:
+    await collection.insert_one({"step": 1}, transaction=transaction)
+    await collection.insert_one({"step": 2}, transaction=transaction)
+    # The transaction will be automatically committed on successful exit.
+    # If an exception occurs, it will be aborted.
+```
+
+### GridFS for Large Files
+
+Store and retrieve large files (e.g., images, videos) seamlessly with GridFS.
+
+```python
+from kover.gridfs import GridFS
+
+# Get a GridFS instance for a database
+fs = await GridFS(client.get_database("files")).indexed()
+
+# Put a file into GridFS
+file_id = await fs.put(b"Hello, large world!", filename="greeting.txt")
+
+# Retrieve the file
+file_info, file_bytes_io = await fs.get_by_file_id(file_id)
+
+log.info(file_info)
+log.info(file_bytes_io.read())
+```
+
+## Found a Bug?
+
+If you find a bug, please [open an issue](https://github.com/megawattka/kover/issues). Better yet, create a pull request with a fix. Contributions are welcome! ❤️

{kover-2.7.2 → kover-2.7.3}/kover/__init__.py

@@ -20,7 +20,7 @@
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 # SOFTWARE.
 
-__version__ = "2.7.2"
+__version__ = "2.7.3"
 __author__ = "megawattka"
 __license__ = "MIT"
 __copyright__ = "Copyright (C) 2024-present megawattka"

{kover-2.7.2 → kover-2.7.3}/kover/bulk_write_builder.py

@@ -24,7 +24,7 @@ class BulkWriteBuilder:
         let: xJsonT | None = None,
         errors_only: bool = False,
         cursor_batch_size: int | None = None,
-        write_concern: str = "majority",
+        write_concern: str | int = "majority",
     ) -> None:
         self.ordered = ordered
         self.bypass_document_validation = bypass_document_validation
@@ -66,29 +66,27 @@ class BulkWriteBuilder:
 
     def add_update(
         self,
-        *updates: Update,
+        update: Update,
         ns: str,
     ) -> None:
         """Adds an Update operations into the builder."""
         idx = self._get_ns_idx(ns)
-        for update in updates:
-            self._operations.append({
-                "update": idx,
-                **update.as_bulk_write_op(),
-            })
+        self._operations.append({
+            "update": idx,
+            **update.as_bulk_write_op(),
+        })
 
     def add_delete(
         self,
-        *deletes: Delete,
+        delete: Delete,
         ns: str,
     ) -> None:
         """Adds an Delete operations into the builder."""
         idx = self._get_ns_idx(ns)
-        for delete in deletes:
-            self._operations.append({
-                "delete": idx,
-                **delete.as_bulk_write_op(),
-            })
+        self._operations.append({
+            "delete": idx,
+            **delete.as_bulk_write_op(),
+        })
 
     def build(self) -> xJsonT:
         """Build the command.

{kover-2.7.2 → kover-2.7.3}/kover/client.py

@@ -14,8 +14,9 @@ from .helpers import (
     filter_non_null,
     maybe_to_dict,
 )
-from .models import BuildInfo, WriteConcern
+from .models import BuildInfo, ReadConcern, WriteConcern
 from .network import MongoTransport, SrvResolver
+from .schema import SchemaGenerator
 from .session import Session
 from .typings import DEFAULT_MONGODB_PORT
 from .uri_parser import parse_uri
@@ -23,11 +24,12 @@ from .uri_parser import parse_uri
 if TYPE_CHECKING:
     from .models import ReplicaSetConfig
     from .network import AuthCredentials
+    from .schema import Document
     from .transaction import Transaction
     from .typings import COMPRESSION_T, DocumentT, xJsonT
 
 
-def create_connection_pool(
+def _create_connection_pool(
     host: str,
     port: int,
     size: int,
@@ -64,6 +66,7 @@ class Kover:
         self._credentials = credentials
         self._compression = compression
         self._application = application
+        self._schema_generator = SchemaGenerator()
 
     async def __aenter__(self) -> Self:
         return self
@@ -115,6 +118,17 @@ class Kover:
         self._write_concern = WriteConcern(w=w, j=j, wtimeout=wtimeout)
         return self
 
+    def generate_schema(self, cls: type[Document]) -> xJsonT:
+        """Generate a JSON schema for the provided Document class.
+
+        Parameters:
+            cls : The Document class for which to generate the schema.
+
+        Returns:
+            A JSON schema as a dictionary.
+        """
+        return self._schema_generator.generate(cls)
+
     @classmethod
     async def from_uri(
         cls,
@@ -154,7 +168,7 @@ class Kover:
             nodes = [host]
 
         args = (nodes[0], parsed.port, parsed.max_pool_size)
-        pool = create_connection_pool(*args, tls=parsed.tls, loop=loop)
+        pool = _create_connection_pool(*args, tls=parsed.tls, loop=loop)
 
         return cls(
             w=parsed.write_concern,
@@ -196,7 +210,7 @@ class Kover:
         Returns:
             An instance of the Kover client.
         """
-        pool = create_connection_pool(
+        pool = _create_connection_pool(
             host, port, max_pool_size, tls=tls, loop=loop)
 
         return cls(
@@ -316,6 +330,25 @@ class Kover:
         """
         await self.request({"dropDatabase": 1.0}, db_name=name)
 
+    # https://www.mongodb.com/docs/manual/reference/command/dropConnections
+    async def drop_connections(
+        self,
+        hosts: list[str],
+        comment: str | None = None,
+    ) -> None:
+        """Drop connections to the specified hosts.
+
+        Parameters:
+            hosts : A list of hostnames whose connections should be dropped.
+            comment : Optional comment for the operation.
+        """
+        document: xJsonT = filter_non_null({
+            "dropConnections": 1.0,
+            "hostAndPort": hosts,
+            "comment": comment,
+        })
+        await self.request(document)
+
     # https://www.mongodb.com/docs/manual/reference/command/replSetInitiate/
     async def replica_set_initiate(
         self,
@@ -487,3 +520,54 @@ class Kover:
             "comment": comment,
         })
         await self.request(command)
+
+    # https://www.mongodb.com/docs/manual/reference/command/getDefaultRWConcern
+    async def get_default_rw_concern(
+        self,
+        *,
+        in_memory: bool = False,
+        comment: str | None = None,
+    ) -> tuple[ReadConcern, WriteConcern]:
+        """Get the default read and write concern settings for the database.
+
+        Parameters:
+            in_memory : If True, returns a WriteConcern instance without
+                querying the server, by default False.
+            comment : Optional comment for the operation.
+
+        Returns:
+            An instance of WriteConcern representing the default settings.
+        """
+        command = filter_non_null({
+            "getDefaultRWConcern": 1.0,
+            "inMemory": in_memory,
+            "comment": comment,
+        })
+        resp = await self.request(command)
+        read_concern = ReadConcern(level=resp["defaultReadConcern"]["level"])
+        write_concern = WriteConcern(w=resp["defaultWriteConcern"]["w"])
+
+        return read_concern, write_concern
+
+    # https://www.mongodb.com/docs/manual/reference/command/getParameter
+    async def get_parameter(self, name: str) -> object:
+        """Get the value of a specific server parameter.
+
+        Parameters:
+            name : The name of the server parameter to retrieve.
+
+        Returns:
+            A Parameter itself.
+        """
+        resp = await self.request({"getParameter": 1.0, name: 1.0})
+        return resp[name]
+
+    # https://www.mongodb.com/docs/manual/reference/command/setParameter
+    async def set_parameter(self, name: str, value: object) -> None:
+        """Set the server parameter at runtime.
+
+        Parameters:
+            name : The name of the server parameter to set.
+            value : The value of that parameter.
+        """
+        await self.request({"setParameter": 1.0, name: value})

{kover-2.7.2 → kover-2.7.3}/kover/database.py

@@ -5,13 +5,14 @@ from __future__ import annotations
 from typing import TYPE_CHECKING
 
 from .collection import Collection
-from .helpers import classrepr, filter_non_null
+from .helpers import classrepr, filter_non_null, maybe_to_dict
 from .models import User
 
 if TYPE_CHECKING:
     from collections.abc import Sequence
 
     from .client import Kover
+    from .models import WriteConcern
     from .session import Transaction
     from .typings import xJsonT
 
@@ -214,6 +215,28 @@ class Database:
         })
         await self.command(command)
 
+    async def drop_all_users_from_database(
+        self,
+        write_concern: WriteConcern | None = None,
+        comment: str | None = None,
+    ) -> int:
+        """Drops all users from the database.
+
+        Parameters:
+            write_concern : Optional write concern for the operation.
+            comment : Optional comment for the operation.
+
+        Returns:
+            The number of users dropped.
+        """
+        command = filter_non_null({
+            "dropAllUsersFromDatabase": 1.0,
+            "writeConcern": maybe_to_dict(write_concern),
+            "comment": comment,
+        })
+        resp = await self.command(command)
+        return resp["n"]
+
     async def grant_roles_to_user(
         self,
         username: str,