Merge branch '45-bump-to-4.0.0'

.github/workflows/test.yaml

@@ -11,7 +11,9 @@ jobs:
       matrix:
         os: ["ubuntu", "windows", "macos"]
         python: ["3.7", "3.8", "3.9", "3.10", "3.11", "3.12"] # https://devguide.python.org/versions/#versions
-
+        exclude:
+        - os: "macos"
+          python: "3.7" # Prevent "The version '3.7' with architecture 'arm64' was not found for macOS 14.4.1"
     runs-on: ${{ matrix.os }}-latest
 
     steps:

.gitignore

@@ -33,4 +33,5 @@ share/python-wheels/
 .installed.cfg
 *.egg
 MANIFEST
-**/__pycache__
+**/__pycache__
+env/

CHANGELOG.md

@@ -0,0 +1,19 @@
+ObjectBox Python ChangeLog
+==========================
+
+4.0.0 (2024-05-16)
+------------------
+
+* ObjectBox now supports vector search ("vector database") to enable efficient similarity searches.
+  This is particularly useful for AI/ML/RAG applications, e.g. image, audio, or text similarity.
+  Other use cases include sematic search or recommendation engines.
+  See https://docs.objectbox.io/ann-vector-search for details.
+* Queries: support for Property-based conditions and logic combinations 
+* Convenient "Store" API deprecates ObjectBox and Builder API
+* New examples added, illustrating an VectorSearch and AI/RAG application
+* Dependency flatbuffers: Updated to 24.3.50
+* Adjusting the version number to match the core version (4.0); we will be aligning on major versions from now on.
+
+Older Versions
+--------------
+Please check https://github.com/objectbox/objectbox-python/releases for details.

Makefile

@@ -63,5 +63,10 @@ clean:					## Clean build artifacts
 	rm -rf *.egg-info
 
 publish:				## Publish the package built by `make build`
-	set -e ; \
-	${PYTHON} -m twine upload --verbose dist/objectbox*.whl
+	set -e
+	@echo "****************************************************************"
+	@echo ">>>  Please enter the API token when asked for a password.  <<<"
+	@echo ">>>  The API token starts with the prefix 'pypi-'.          <<<"
+	@echo ">>>  See https://pypi.org/help/#apitoken for details.       <<<"
+	@echo "****************************************************************"
+	${PYTHON} -m twine upload -u "__token__" --verbose dist/objectbox*.whl

README.md

@@ -1,83 +1,57 @@
-ObjectBox Python API
-====================
-[ObjectBox](https://objectbox.io) is a superfast database for objects, now also available for Python (3.4+) with a simple CRUD API.
+ObjectBox Python
+================
+[ObjectBox](https://objectbox.io) Python is a lightweight yet powerful on-device database & vector database.
+Store Python objects and vectors directly with an easy-to-use CRUD API while enjoying exceptional speed and efficiency.
 And because it's an embedded database, there's no setup required.
-
-## Table of Contents:
-- [Getting Started](#getting-started)
-   - [Model IDs and UIDs](#model-ids-and-uids)
-   - [model.py](#modelpy)
-- [Using ObjectBox](#using-objectbox)
-- [Some features](#some-features)
-- [Coming in the future](#coming-in-the-future)
-- [Help wanted](#help-wanted)
-- [Feedback](#feedback)
-- [License](#license)
 
----
+Its advanced vector search empowers AI for a variety of applications, including RAG AI, generative AI,
+and similarity searches.
 
-Getting started
----------------
-First of all, install the latest version:
+Designed for high performance, the ObjectBox database runs locally on-device.
+As an offline-first solution, ObjectBox makes sure your app reliably works offline as well as online
+(via [Sync](https://objectbox.io/sync/)).
 
-```bash
-pip install --upgrade objectbox
-```
-
-To start using ObjectBox as a storage for your data, you need to define your model first.
-The model consists of Python classes annotated with `@Entity` decorator.
-
-### Model IDs and UIDs
+_Table of Contents_
 
-Each Entity has to have an ID (unique among entities).
-Properties need an ID as well (unique inside one Entity).
-Both Entities and Properties must also have an UID, which is a globally unique identifier.
-
-For other ObjectBox supported languages, the binding takes care of assigning these IDs/UIDs but this feature is not yet implemented for Python.
-To learn more, see [ObjectBox Java documentation](https://docs.objectbox.io/advanced/meta-model-ids-and-uids)
-
-#### model.py
+- [Feature Highlights](#feature-highlights)
+- [Code Example (CRUD - Create, Read, Update, Delete)](#code-example-crud---create-read-update-delete)
+- [Getting Started](#getting-started)
+- [Alpha Notes](#alpha-notes)
+- [Help wanted](#help-wanted)
+- [Feedback](#feedback)
+- [License](#license)
 
-```python
-from objectbox.model import *
-
-@Entity(id=1, uid=1)
-class Person:
-    id = Id(id=1, uid=1001)
-    name = Property(str, id=2, uid=1002)
-    is_enabled = Property(bool, id=3, uid=1003)
-    # int can be stored with 64 (default), 32, 16 or 8 bit precision.
-    int64 = Property(int, id=4, uid=1004)
-    int32 = Property(int, type=PropertyType.int, id=5, uid=1005)
-    int16 = Property(int, type=PropertyType.short, id=6, uid=1006)
-    int8 = Property(int, type=PropertyType.byte, id=7, uid=1007)
-    # float can be stored with 64 or 32 (default) bit precision.
-    float64 = Property(float, id=8, uid=1008)
-    float32 = Property(float, type=PropertyType.float, id=9, uid=1009)
-    byte_array = Property(bytes, id=10, uid=1010)
-    # Regular properties are not stored.
-    transient = ""
-```
+Feature Highlights
+------------------
 
-### Using ObjectBox
+🏁 **On-device vector database** - for AI apps that work any place.\
+🏁 **High performance** - superfast response rates enabling real-time applications.\
+🪂 **ACID compliant** - Atomic, Consistent, Isolated, Durable.\
+🌱 **Scalable** - grows with your app, handling millions of objects with ease.\
+💚 **Sustainable** - frugal on CPU, Memory and battery / power use, reducing CO2 emissions.\
+💐 **[Queries](https://docs.objectbox.io/queries)** - filter data as needed, even across relations.\
+💻 **Multiplatform** - Get native speed on your favorite platforms.\
+* Linux x86-64 (64-bit)
+* Linux ARMv6hf (e.g. Raspberry PI Zero)
+* Linux ARMv7hf (e.g. Raspberry PI 3)
+* Linux ARMv8   (e.g. Raspberry PI 4, 5, etc.)
+* MacOS x86-64 and arm64 (Intel 64-bit and Apple Silicon)
+* Windows x86-64 (64-bit)
 
-To actually use the database, you launch (or "build") it with the model you've just defined.
-Afterwards, you can reuse the instance (`ob` in the example below) and use it to access "Entity Boxes" which hold your objects.
+#### Code Example (CRUD - Create, Read, Update, Delete)
 
-#### program.py
+What does using ObjectBox in Python look like?
 
 ```python
 import objectbox
+
 # from mypackage.model import Person
 
-# Configure ObjectBox: should be done only once in the whole program and the "ob" variable should be kept around
-model = objectbox.Model()
-model.entity(Person, last_property_id=objectbox.model.IdUid(10, 1010))
-model.last_entity_id = objectbox.model.IdUid(1, 1)
-ob = objectbox.Builder().model(model).directory("db").build()
+# The ObjectBox Store represents a database; keep it around...
+store = objectbox.Store(model=model)
 
-# Open the box of "Person" entity. This can be called many times but you can also pass the variable around
-box = objectbox.Box(ob, Person)
+# Get a box for the "Person" entity; a Box is the main interaction point with objects and the database.
+box = store.box(Person)
 
 person = Person()
 person.name = "Joe Green"
@@ -88,65 +62,46 @@ box.put(person)       # Update
 box.remove(person)    # Delete
 ```
 
-Additionally, see the [TaskList example app](https://github.com/objectbox/objectbox-python/tree/main/example). After checking out this repository to run the example:
+Getting started
+---------------
+Latest version: 4.0.0a0 (2024-05-15)
+
+To install or update the latest version of ObjectBox, run this:
+
+```bash
+pip install --upgrade --pre objectbox  # "--pre" because you want to get the 4.0.0 alpha version
 ```
-// Set up virtual environment, download ObjectBox libraries
-make depend
+Now you are ready to use ObjectBox in your Python project.
 
-// Activate virtual environment...
-// ...on Linux
-source .venv/bin/activate
-// ...on Windows
-.venv\Scripts\activate
+Head over to the **[ObjectBox documentation](https://docs.objectbox.io)**
+and learn how to setup your first entity classes.
 
-// Run the example
-python3 -m example
+### Examples
 
-// Once done, leave the virtual environment
-deactivate
-```
+Do you prefer to dive right into working examples?
+We have you covered in the [example](example/) folder.
+It comes with a task list application and a vector search example using cities.
+Additionally, for AI enthusiasts, we provide an "ollama" example,
+which integrates a local LLM (via [ollama](https://ollama.com))
+with ObjectBox to manage and search embeddings effectively.
 
-For more information and code examples, see the tests folder. The docs for other languages may also help you understand the basics.
-
-* ObjectBox Java/Dart/Flutter - https://docs.objectbox.io
-* ObjectBox Go - https://golang.objectbox.io
-* ObjectBox Swift - https://swift.objectbox.io
-
-Some features
--------------
-* Automatic transactions (ACID compliant)
-* Bulk operations
-* Vector types, e.g. for AI vector embeddings
-* Platforms supported with native speed:
-  * Linux x86-64 (64-bit)
-  * Linux ARMv6hf (e.g. Raspberry PI Zero)
-  * Linux ARMv7hf (e.g. Raspberry PI 3; available only on request)
-  * Linux ARMv8   (e.g. Raspberry PI 4)
-  * MacOS x86-64 and arm64 (Intel 64-bit and Apple Silicon)
-  * Windows x86-64 (64-bit)
-
-Coming in the future
---------------------
-The goodness you know from the other ObjectBox language-bindings, e.g.,
-
-* model management (no need to manually set id/uid)
-* automatic model migration (no schema upgrade scripts etc.)
-* powerful queries
-* relations (to-one, to-many)
-* asynchronous operations
-* secondary indexes
+Alpha Notes
+-----------
+While ObjectBox Python is powered by a rock stable core written in C/C++, we label our Python binding still "alpha."
+We do this to manage expectations as some quality of life improvements are yet to come to our Python binding.
+This is mostly about "model management," which still requires you to do some manual coding setup, e.g. for model IDs.
+The final release will take care of this for you automatically.
 
 Help wanted
 -----------
-ObjectBox for Python is still in an early stage with limited feature set (compared to our other supported languages).
-To bring all these features to Python, we're asking the community to help out. PRs are more than welcome!
+ObjectBox for Python is open to contributions.
 The ObjectBox team will try its best to guide you and answer questions.
 See [CONTRIBUTING.md](https://github.com/objectbox/objectbox-python/blob/main/CONTRIBUTING.md) to get started.
 
 Feedback
 --------
-Also, please let us know your feedback by opening an issue: for example, if you experience errors or if you have ideas
-for how to improve the API. Thanks!
+We are looking for your feedback!
+Please let us know what you think about ObjectBox for Python and how we can improve it.
 
 License
 -------

benchmark.py

@@ -1,7 +1,7 @@
 import objectbox
 import time
 from tests.model import TestEntity
-from tests.common import remove_test_dir, load_empty_test_objectbox
+from tests.common import remove_test_dir, load_empty_test_default_store
 
 
 class ObjectBoxPerf:
@@ -10,8 +10,8 @@ class ObjectBoxPerf:
     """
 
     def __init__(self):
-        self.ob = load_empty_test_objectbox()
-        self.box = objectbox.Box(self.ob, TestEntity)
+        self.store = load_empty_test_default_store()
+        self.box = store.box(TestEntity)
 
     def remove_all(self):
         self.box.remove_all()

download-c-lib.py

@@ -6,7 +6,7 @@
 # Script used to download objectbox-c shared libraries for all supported platforms. Execute by running `make get-lib`
 # on first checkout of this repo and any time after changing the objectbox-c lib version.
 
-version = "v0.21.0"  # see objectbox/c.py required_version
+version = "v4.0.0"  # see objectbox/c.py required_version
 variant = 'objectbox'  # or 'objectbox-sync'
 
 base_url = "https://github.com/objectbox/objectbox-c/releases/download/"
@@ -49,6 +49,7 @@ def download(rel_path: str):
 
     # Download the file from `url`, save it in a temporary directory and get the path to it (e.g. '/tmp/tmpb48zma')
     source_url = url_for(rel_path);
+    print(f"URL {source_url}")
     tmp_file, headers = urllib.request.urlretrieve(source_url)
 
     # extract the file

example/README.md

@@ -0,0 +1,75 @@
+# ObjectBox-Python Examples
+
+The following examples are available from this repository.
+
+## Application Example: Tasks
+
+This is our classic Tasks application using a CLI.
+
+```
+cd example
+python -m tasks
+
+Welcome to the ObjectBox tasks-list app example. Type help or ? for a list of commands.
+> new buy oat
+> new buy yeast
+> new bake bread
+> ls
+ ID  Created                        Finished                       Text
+  1  Mon Apr 22 11:02:27 2024                                      buy oat
+  2  Mon Apr 22 11:02:30 2024                                      buy yeast
+  3  Mon Apr 22 11:02:34 2024                                      bake bread
+> done 1
+> done 2
+> ls
+> ls
+ ID  Created                        Finished                       Text
+  1  Mon Apr 22 11:02:27 2024       Mon Apr 22 11:03:02 2024       buy oat
+  2  Mon Apr 22 11:02:30 2024       Mon Apr 22 11:03:18 2024       buy yeast
+  3  Mon Apr 22 11:02:34 2024                                      bake bread
+> exit
+```
+
+## Vector-Search Example: Cities
+
+This example application starts with a pre-defined set of capital cities and their geo coordinates. 
+It allows to search for nearest neighbors of a city (`city_neighbors`) or by coordinates (`neighbors`) as well as adding more locations (`add`).
+
+```
+python -m vectorsearch-cities
+Welcome to the ObjectBox vectorsearch-cities example. Type help or ? for a list of commands.
+> ls
+ID   Name                        Latitude  Longitude
+  1  Abuja                           9.08       7.40
+  2  Accra                           5.60      -0.19
+[..]
+212  Yerevan                        40.19      44.52
+213  Zagreb                         45.81      15.98
+> ls Ber
+ID   Name                        Latitude  Longitude
+ 28  Berlin                         52.52      13.40
+ 29  Bern                           46.95       7.45
+> city_neighbors Berlin
+ID   Name                        Latitude  Longitude  Score
+147  Prague                         50.08      14.44   7.04
+ 49  Copenhagen                     55.68      12.57  10.66
+200  Vienna                         48.21      16.37  27.41
+ 34  Bratislava                     48.15      17.11  32.82
+ 89  Ljubljana                      46.06      14.51  42.98
+> neighbors 6,52.52,13.405
+ID   Name                        Latitude  Longitude  Score
+ 28  Berlin                         52.52      13.40   0.00
+147  Prague                         50.08      14.44   7.04
+ 49  Copenhagen                     55.68      12.57  10.66
+200  Vienna                         48.21      16.37  27.41
+ 34  Bratislava                     48.15      17.11  32.82
+ 89  Ljubljana                      46.06      14.51  42.98
+ > add Area51, 37.23, -115.81
+ > city_neighbors Area51
+ID   Name                        Latitude  Longitude  Score
+107  Mexico City                    19.43     -99.13  594.86
+ 27  Belmopan                       17.25     -88.76  1130.92
+ 64  Guatemala City                 14.63     -90.51  1150.79
+164  San Salvador                   13.69     -89.22  1261.12
+ 67  Havana                         23.11     -82.37  1317.73
+```