docs: update readme

Author: roeap

.github/workflows/release.yaml

@@ -23,6 +23,7 @@ jobs:
             echo "Cargo metadata has version set to ${CURR_VER}, but got pushed tag ${PUSHED_TAG}."
             exit 1
           fi
+      - run: rm object-store/README.md && cp README.md object-store/README.md
 
   release-pypi-mac:
     needs: validate-release-tag

README.md

@@ -5,41 +5,69 @@
 <a href="https://github.com/psf/black"><img alt="code style: black" src="https://img.shields.io/badge/code%20style-black-000000.svg"></a>
 </p>
 
-Recently the excellent [`object_store`](https://crates.io/crates/object_store) crate has been
-[donated](https://www.influxdata.com/blog/rust-object-store-donation/) to the Apache Software Foundation.
+Recently, the excellent [`object_store`](https://crates.io/crates/object_store) crate has been
+[donated](https://www.influxdata.com/blog/rust-object-store-donation/) to the Apache Software Foundation
+And powers many popular projects like [datafusion](https://github.com/apache/arrow-datafusion),
+[InfluxDB IOX](https://github.com/influxdata/influxdb_iox), [delta-rs](https://github.com/delta-io/delta-rs), and more.
+THe `object-store-python` package provides python bindings as well some convenience and pythonic adjustments
+around the native APIs.
 
-## Prerequisites
+## Installation
 
-- [poetry](https://python-poetry.org/docs/)
-- [Rust toolchain](https://www.rust-lang.org/tools/install)
-- [just](https://github.com/casey/just#readme)
-
-## Development
-
-If you do not have [`just`](<(https://github.com/casey/just#readme)>) installed and do not wish to install it,
-have a look at the [`justfile`](https://github.com/roeap/object-store-python/blob/main/justfile) to see the raw commands.
-
-To set up the development environment, and install a dev version of the native package just run:
+The `object-store-python` package is available on PyPI and can be installed via
 
 ```sh
-just init
+poetry add object-store-python
 ```
 
-This will also configure [`pre-commit`](https://pre-commit.com/) hooks in the repository.
-
-To run the rust as well as python tests:
+or using pip
 
 ```sh
-just test
+pip install object-store-python
 ```
 
 ## Usage
 
+The main idea behind the `ObjectStore` API is to provide a common interface to various
+storage backends including the objects stores from most major cloud providers. The APIs
+are very focussed and taylored towards modern cloud native applications by hiding away
+many features (and complexities) encountered in full fledges file systems.
+
+Among the included backend are:
+
+- Amazon S3 and S3 compliant APIs
+- Google Cloud Storage Buckets
+- Azure Blob Gen1 and Gen2 accounts (including ADLS Gen2)
+- local storage
+- in-memory store
+
+Additionally, an integration is provided to seamlessly work with the (py)arrow ecosystem.
+
 ### `ObjectStore` api
 
-The `object-store-python` tries to directly exposes the APIs defined on the
-[`ObjectStore`](https://docs.rs/object_store/latest/object_store/trait.ObjectStore.html) trait
-in the underlying rust crate.
+```py
+from object_store import ObjectStore, ObjectMeta
+
+# we use an in-memory store for demonstration purposes.
+# data will not be persisted and is not shared across store instances
+store = ObjectStore("memory://")
+
+store.put("data", b"some data")
+
+data = store.get("data")
+assert data == b"some data"
+
+blobs = store.list()
+
+meta: ObjectMeta = store.head("data")
+
+range = store.get_range("data", start=0, length=4)
+assert range == b"some"
+
+store.copy("data", "copied")
+copied = store.get("copied")
+assert copied == data
+```
 
 ### with `pyarrow`
 
@@ -64,3 +92,30 @@ pq.write_table(table.slice(5, 10), "data/data2.parquet", filesystem=store)
 
 dataset = ds.dataset("data", format="parquet", filesystem=store)
 ```
+
+## Development
+
+### Prerequisites
+
+- [poetry](https://python-poetry.org/docs/)
+- [Rust toolchain](https://www.rust-lang.org/tools/install)
+- [just](https://github.com/casey/just#readme)
+
+### Running tests
+
+If you do not have [`just`](<(https://github.com/casey/just#readme)>) installed and do not wish to install it,
+have a look at the [`justfile`](https://github.com/roeap/object-store-python/blob/main/justfile) to see the raw commands.
+
+To set up the development environment, and install a dev version of the native package just run:
+
+```sh
+just init
+```
+
+This will also configure [`pre-commit`](https://pre-commit.com/) hooks in the repository.
+
+To run the rust as well as python tests:
+
+```sh
+just test
+```