Skip to content

Commit ae0cf3b

Browse files
greenrobotgreenrobot
committed
Merge branch '45-bump-to-4.0.0'
2 parents 1395fa9 + 3be80f7 commit ae0cf3b

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

51 files changed

+3113
-729
lines changed

‎.github/workflows/test.yaml

+3-1
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,9 @@ jobs:
1111
matrix:
1212
os: ["ubuntu", "windows", "macos"]
1313
python: ["3.7", "3.8", "3.9", "3.10", "3.11", "3.12"] # https://devguide.python.org/versions/#versions
14-
14+
exclude:
15+
- os: "macos"
16+
python: "3.7" # Prevent "The version '3.7' with architecture 'arm64' was not found for macOS 14.4.1"
1517
runs-on: ${{ matrix.os }}-latest
1618

1719
steps:

‎.gitignore

+2-1
Original file line numberDiff line numberDiff line change
@@ -33,4 +33,5 @@ share/python-wheels/
3333
.installed.cfg
3434
*.egg
3535
MANIFEST
36-
**/__pycache__
36+
**/__pycache__
37+
env/

‎CHANGELOG.md

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

‎Makefile

+7-2
Original file line numberDiff line numberDiff line change
@@ -63,5 +63,10 @@ clean: ## Clean build artifacts
6363
rm -rf *.egg-info
6464

6565
publish: ## Publish the package built by `make build`
66-
set -e ; \
67-
${PYTHON} -m twine upload --verbose dist/objectbox*.whl
66+
set -e
67+
@echo "****************************************************************"
68+
@echo ">>> Please enter the API token when asked for a password. <<<"
69+
@echo ">>> The API token starts with the prefix 'pypi-'. <<<"
70+
@echo ">>> See https://pypi.org/help/#apitoken for details. <<<"
71+
@echo "****************************************************************"
72+
${PYTHON} -m twine upload -u "__token__" --verbose dist/objectbox*.whl

‎README.md

+66-111
Original file line numberDiff line numberDiff line change
@@ -1,83 +1,57 @@
1-
ObjectBox Python API
2-
====================
3-
[ObjectBox](https://objectbox.io) is a superfast database for objects, now also available for Python (3.4+) with a simple CRUD API.
1+
ObjectBox Python
2+
================
3+
[ObjectBox](https://objectbox.io) Python is a lightweight yet powerful on-device database & vector database.
4+
Store Python objects and vectors directly with an easy-to-use CRUD API while enjoying exceptional speed and efficiency.
45
And because it's an embedded database, there's no setup required.
5-
6-
## Table of Contents:
7-
- [Getting Started](#getting-started)
8-
- [Model IDs and UIDs](#model-ids-and-uids)
9-
- [model.py](#modelpy)
10-
- [Using ObjectBox](#using-objectbox)
11-
- [Some features](#some-features)
12-
- [Coming in the future](#coming-in-the-future)
13-
- [Help wanted](#help-wanted)
14-
- [Feedback](#feedback)
15-
- [License](#license)
166

17-
---
7+
Its advanced vector search empowers AI for a variety of applications, including RAG AI, generative AI,
8+
and similarity searches.
189

19-
Getting started
20-
---------------
21-
First of all, install the latest version:
10+
Designed for high performance, the ObjectBox database runs locally on-device.
11+
As an offline-first solution, ObjectBox makes sure your app reliably works offline as well as online
12+
(via [Sync](https://objectbox.io/sync/)).
2213

23-
```bash
24-
pip install --upgrade objectbox
25-
```
26-
27-
To start using ObjectBox as a storage for your data, you need to define your model first.
28-
The model consists of Python classes annotated with `@Entity` decorator.
29-
30-
### Model IDs and UIDs
14+
_Table of Contents_
3115

32-
Each Entity has to have an ID (unique among entities).
33-
Properties need an ID as well (unique inside one Entity).
34-
Both Entities and Properties must also have an UID, which is a globally unique identifier.
35-
36-
For other ObjectBox supported languages, the binding takes care of assigning these IDs/UIDs but this feature is not yet implemented for Python.
37-
To learn more, see [ObjectBox Java documentation](https://docs.objectbox.io/advanced/meta-model-ids-and-uids)
38-
39-
#### model.py
16+
- [Feature Highlights](#feature-highlights)
17+
- [Code Example (CRUD - Create, Read, Update, Delete)](#code-example-crud---create-read-update-delete)
18+
- [Getting Started](#getting-started)
19+
- [Alpha Notes](#alpha-notes)
20+
- [Help wanted](#help-wanted)
21+
- [Feedback](#feedback)
22+
- [License](#license)
4023

41-
```python
42-
from objectbox.model import *
43-
44-
@Entity(id=1, uid=1)
45-
class Person:
46-
id = Id(id=1, uid=1001)
47-
name = Property(str, id=2, uid=1002)
48-
is_enabled = Property(bool, id=3, uid=1003)
49-
# int can be stored with 64 (default), 32, 16 or 8 bit precision.
50-
int64 = Property(int, id=4, uid=1004)
51-
int32 = Property(int, type=PropertyType.int, id=5, uid=1005)
52-
int16 = Property(int, type=PropertyType.short, id=6, uid=1006)
53-
int8 = Property(int, type=PropertyType.byte, id=7, uid=1007)
54-
# float can be stored with 64 or 32 (default) bit precision.
55-
float64 = Property(float, id=8, uid=1008)
56-
float32 = Property(float, type=PropertyType.float, id=9, uid=1009)
57-
byte_array = Property(bytes, id=10, uid=1010)
58-
# Regular properties are not stored.
59-
transient = ""
60-
```
24+
Feature Highlights
25+
------------------
6126

62-
### Using ObjectBox
27+
🏁 **On-device vector database** - for AI apps that work any place.\
28+
🏁 **High performance** - superfast response rates enabling real-time applications.\
29+
🪂 **ACID compliant** - Atomic, Consistent, Isolated, Durable.\
30+
🌱 **Scalable** - grows with your app, handling millions of objects with ease.\
31+
💚 **Sustainable** - frugal on CPU, Memory and battery / power use, reducing CO2 emissions.\
32+
💐 **[Queries](https://docs.objectbox.io/queries)** - filter data as needed, even across relations.\
33+
💻 **Multiplatform** - Get native speed on your favorite platforms.\
34+
* Linux x86-64 (64-bit)
35+
* Linux ARMv6hf (e.g. Raspberry PI Zero)
36+
* Linux ARMv7hf (e.g. Raspberry PI 3)
37+
* Linux ARMv8 (e.g. Raspberry PI 4, 5, etc.)
38+
* MacOS x86-64 and arm64 (Intel 64-bit and Apple Silicon)
39+
* Windows x86-64 (64-bit)
6340

64-
To actually use the database, you launch (or "build") it with the model you've just defined.
65-
Afterwards, you can reuse the instance (`ob` in the example below) and use it to access "Entity Boxes" which hold your objects.
41+
#### Code Example (CRUD - Create, Read, Update, Delete)
6642

67-
#### program.py
43+
What does using ObjectBox in Python look like?
6844

6945
```python
7046
import objectbox
47+
7148
# from mypackage.model import Person
7249

73-
# Configure ObjectBox: should be done only once in the whole program and the "ob" variable should be kept around
74-
model = objectbox.Model()
75-
model.entity(Person, last_property_id=objectbox.model.IdUid(10, 1010))
76-
model.last_entity_id = objectbox.model.IdUid(1, 1)
77-
ob = objectbox.Builder().model(model).directory("db").build()
50+
# The ObjectBox Store represents a database; keep it around...
51+
store = objectbox.Store(model=model)
7852

79-
# Open the box of "Person" entity. This can be called many times but you can also pass the variable around
80-
box = objectbox.Box(ob, Person)
53+
# Get a box for the "Person" entity; a Box is the main interaction point with objects and the database.
54+
box = store.box(Person)
8155

8256
person = Person()
8357
person.name = "Joe Green"
@@ -88,65 +62,46 @@ box.put(person) # Update
8862
box.remove(person) # Delete
8963
```
9064

91-
Additionally, see the [TaskList example app](https://github.com/objectbox/objectbox-python/tree/main/example). After checking out this repository to run the example:
65+
Getting started
66+
---------------
67+
Latest version: 4.0.0a0 (2024-05-15)
68+
69+
To install or update the latest version of ObjectBox, run this:
70+
71+
```bash
72+
pip install --upgrade --pre objectbox # "--pre" because you want to get the 4.0.0 alpha version
9273
```
93-
// Set up virtual environment, download ObjectBox libraries
94-
make depend
74+
Now you are ready to use ObjectBox in your Python project.
9575

96-
// Activate virtual environment...
97-
// ...on Linux
98-
source .venv/bin/activate
99-
// ...on Windows
100-
.venv\Scripts\activate
76+
Head over to the **[ObjectBox documentation](https://docs.objectbox.io)**
77+
and learn how to setup your first entity classes.
10178

102-
// Run the example
103-
python3 -m example
79+
### Examples
10480

105-
// Once done, leave the virtual environment
106-
deactivate
107-
```
81+
Do you prefer to dive right into working examples?
82+
We have you covered in the [example](example/) folder.
83+
It comes with a task list application and a vector search example using cities.
84+
Additionally, for AI enthusiasts, we provide an "ollama" example,
85+
which integrates a local LLM (via [ollama](https://ollama.com))
86+
with ObjectBox to manage and search embeddings effectively.
10887

109-
For more information and code examples, see the tests folder. The docs for other languages may also help you understand the basics.
110-
111-
* ObjectBox Java/Dart/Flutter - https://docs.objectbox.io
112-
* ObjectBox Go - https://golang.objectbox.io
113-
* ObjectBox Swift - https://swift.objectbox.io
114-
115-
Some features
116-
-------------
117-
* Automatic transactions (ACID compliant)
118-
* Bulk operations
119-
* Vector types, e.g. for AI vector embeddings
120-
* Platforms supported with native speed:
121-
* Linux x86-64 (64-bit)
122-
* Linux ARMv6hf (e.g. Raspberry PI Zero)
123-
* Linux ARMv7hf (e.g. Raspberry PI 3; available only on request)
124-
* Linux ARMv8 (e.g. Raspberry PI 4)
125-
* MacOS x86-64 and arm64 (Intel 64-bit and Apple Silicon)
126-
* Windows x86-64 (64-bit)
127-
128-
Coming in the future
129-
--------------------
130-
The goodness you know from the other ObjectBox language-bindings, e.g.,
131-
132-
* model management (no need to manually set id/uid)
133-
* automatic model migration (no schema upgrade scripts etc.)
134-
* powerful queries
135-
* relations (to-one, to-many)
136-
* asynchronous operations
137-
* secondary indexes
88+
Alpha Notes
89+
-----------
90+
While ObjectBox Python is powered by a rock stable core written in C/C++, we label our Python binding still "alpha."
91+
We do this to manage expectations as some quality of life improvements are yet to come to our Python binding.
92+
This is mostly about "model management," which still requires you to do some manual coding setup, e.g. for model IDs.
93+
The final release will take care of this for you automatically.
13894

13995
Help wanted
14096
-----------
141-
ObjectBox for Python is still in an early stage with limited feature set (compared to our other supported languages).
142-
To bring all these features to Python, we're asking the community to help out. PRs are more than welcome!
97+
ObjectBox for Python is open to contributions.
14398
The ObjectBox team will try its best to guide you and answer questions.
14499
See [CONTRIBUTING.md](https://github.com/objectbox/objectbox-python/blob/main/CONTRIBUTING.md) to get started.
145100

146101
Feedback
147102
--------
148-
Also, please let us know your feedback by opening an issue: for example, if you experience errors or if you have ideas
149-
for how to improve the API. Thanks!
103+
We are looking for your feedback!
104+
Please let us know what you think about ObjectBox for Python and how we can improve it.
150105

151106
License
152107
-------

‎benchmark.py

+3-3
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
import objectbox
22
import time
33
from tests.model import TestEntity
4-
from tests.common import remove_test_dir, load_empty_test_objectbox
4+
from tests.common import remove_test_dir, load_empty_test_default_store
55

66

77
class ObjectBoxPerf:
@@ -10,8 +10,8 @@ class ObjectBoxPerf:
1010
"""
1111

1212
def __init__(self):
13-
self.ob = load_empty_test_objectbox()
14-
self.box = objectbox.Box(self.ob, TestEntity)
13+
self.store = load_empty_test_default_store()
14+
self.box = store.box(TestEntity)
1515

1616
def remove_all(self):
1717
self.box.remove_all()

‎download-c-lib.py

+2-1
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@
66
# Script used to download objectbox-c shared libraries for all supported platforms. Execute by running `make get-lib`
77
# on first checkout of this repo and any time after changing the objectbox-c lib version.
88

9-
version = "v0.21.0" # see objectbox/c.py required_version
9+
version = "v4.0.0" # see objectbox/c.py required_version
1010
variant = 'objectbox' # or 'objectbox-sync'
1111

1212
base_url = "https://github.com/objectbox/objectbox-c/releases/download/"
@@ -49,6 +49,7 @@ def download(rel_path: str):
4949

5050
# Download the file from `url`, save it in a temporary directory and get the path to it (e.g. '/tmp/tmpb48zma')
5151
source_url = url_for(rel_path);
52+
print(f"URL {source_url}")
5253
tmp_file, headers = urllib.request.urlretrieve(source_url)
5354

5455
# extract the file

‎example/README.md

+75
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
# ObjectBox-Python Examples
2+
3+
The following examples are available from this repository.
4+
5+
## Application Example: Tasks
6+
7+
This is our classic Tasks application using a CLI.
8+
9+
```
10+
cd example
11+
python -m tasks
12+
13+
Welcome to the ObjectBox tasks-list app example. Type help or ? for a list of commands.
14+
> new buy oat
15+
> new buy yeast
16+
> new bake bread
17+
> ls
18+
ID Created Finished Text
19+
1 Mon Apr 22 11:02:27 2024 buy oat
20+
2 Mon Apr 22 11:02:30 2024 buy yeast
21+
3 Mon Apr 22 11:02:34 2024 bake bread
22+
> done 1
23+
> done 2
24+
> ls
25+
> ls
26+
ID Created Finished Text
27+
1 Mon Apr 22 11:02:27 2024 Mon Apr 22 11:03:02 2024 buy oat
28+
2 Mon Apr 22 11:02:30 2024 Mon Apr 22 11:03:18 2024 buy yeast
29+
3 Mon Apr 22 11:02:34 2024 bake bread
30+
> exit
31+
```
32+
33+
## Vector-Search Example: Cities
34+
35+
This example application starts with a pre-defined set of capital cities and their geo coordinates.
36+
It allows to search for nearest neighbors of a city (`city_neighbors`) or by coordinates (`neighbors`) as well as adding more locations (`add`).
37+
38+
```
39+
python -m vectorsearch-cities
40+
Welcome to the ObjectBox vectorsearch-cities example. Type help or ? for a list of commands.
41+
> ls
42+
ID Name Latitude Longitude
43+
1 Abuja 9.08 7.40
44+
2 Accra 5.60 -0.19
45+
[..]
46+
212 Yerevan 40.19 44.52
47+
213 Zagreb 45.81 15.98
48+
> ls Ber
49+
ID Name Latitude Longitude
50+
28 Berlin 52.52 13.40
51+
29 Bern 46.95 7.45
52+
> city_neighbors Berlin
53+
ID Name Latitude Longitude Score
54+
147 Prague 50.08 14.44 7.04
55+
49 Copenhagen 55.68 12.57 10.66
56+
200 Vienna 48.21 16.37 27.41
57+
34 Bratislava 48.15 17.11 32.82
58+
89 Ljubljana 46.06 14.51 42.98
59+
> neighbors 6,52.52,13.405
60+
ID Name Latitude Longitude Score
61+
28 Berlin 52.52 13.40 0.00
62+
147 Prague 50.08 14.44 7.04
63+
49 Copenhagen 55.68 12.57 10.66
64+
200 Vienna 48.21 16.37 27.41
65+
34 Bratislava 48.15 17.11 32.82
66+
89 Ljubljana 46.06 14.51 42.98
67+
> add Area51, 37.23, -115.81
68+
> city_neighbors Area51
69+
ID Name Latitude Longitude Score
70+
107 Mexico City 19.43 -99.13 594.86
71+
27 Belmopan 17.25 -88.76 1130.92
72+
64 Guatemala City 14.63 -90.51 1150.79
73+
164 San Salvador 13.69 -89.22 1261.12
74+
67 Havana 23.11 -82.37 1317.73
75+
```

0 commit comments

Comments
 (0)