This is an automated email from the ASF dual-hosted git repository.
chaokunyang pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/fory.git
The following commit(s) were added to refs/heads/main by this push:
new 08dad965b docs: Improve pyfory PyPI documentation (#2498)
08dad965b is described below
commit 08dad965b1c9d68e3825b1f1c1d856a440e6d312
Author: Emre Şafak <[email protected]>
AuthorDate: Fri Aug 22 22:19:04 2025 -0400
docs: Improve pyfory PyPI documentation (#2498)
## What does this PR do?
The existing PyPI documentation for `pyfory` was a single line and
uninformative. This change improves the documentation by:
1. Creating a new `python/README.md` with a clear and concise
description of the project, installation instructions, and usage
examples. This file is used to generate the PyPI page description.
2. Moving the developer-focused build and test instructions to a new
`python/CONTRIBUTING.md` file.
This will provide a much better experience for Python developers who
discover `pyfory` on PyPI, similar to the documentation for other
popular libraries like `opendal` and `msgpack`.
## Related issues
Closes #2488
---
python/{README.md => CONTRIBUTING.md} | 12 ++--
python/README.md | 131 +++++++++++++++++++++-------------
2 files changed, 87 insertions(+), 56 deletions(-)
diff --git a/python/README.md b/python/CONTRIBUTING.md
similarity index 89%
copy from python/README.md
copy to python/CONTRIBUTING.md
index fba167957..fbe24c77d 100644
--- a/python/README.md
+++ b/python/CONTRIBUTING.md
@@ -1,8 +1,8 @@
-# Apache Fory™ Python
+# Contributing to Apache Fory Python
-Fory is a blazingly-fast multi-language serialization framework powered by
just-in-time compilation and zero-copy.
+This document provides instructions for building and testing the `pyfory`
package.
-## Build Fory Python
+## Building
```bash
cd python
@@ -37,7 +37,7 @@ cd python
pytest -v -s .
```
-## Code Style
+## Formatting
```bash
cd python
@@ -45,7 +45,7 @@ pip install ruff
ruff format python
```
-## Debug
+## Debugging
```bash
cd python
@@ -62,7 +62,7 @@ FORY_DEBUG=true python setup.py build_ext --inplace
cygdb build
```
-## Debug with lldb
+### Debugging with lldb
```bash
lldb
diff --git a/python/README.md b/python/README.md
index fba167957..fb29c7dc5 100644
--- a/python/README.md
+++ b/python/README.md
@@ -1,73 +1,104 @@
# Apache Fory™ Python
-Fory is a blazingly-fast multi-language serialization framework powered by
just-in-time compilation and zero-copy.
+[](https://github.com/apache/fory/actions/workflows/ci.yml)
+[](https://pypi.org/project/pyfory/)
+[](https://join.slack.com/t/fory-project/shared_invite/zt-36g0qouzm-kcQSvV_dtfbtBKHRwT5gsw)
+[](https://x.com/ApacheFory)
-## Build Fory Python
+**Apache Fory** (formerly _Fury_) is a blazing fast multi-language
serialization framework powered by **JIT** (just-in-time compilation) and
**zero-copy**, providing up to 170x performance and ease of use.
+
+This package provides the Python bindings for Apache Fory.
+
+## Installation
+
+You can install `pyfory` using pip:
```bash
-cd python
-# Uninstall numpy first so that when we install pyarrow, it will install the
correct numpy version automatically.
-# For Python versions less than 3.13, numpy 2 is not currently supported.
-pip uninstall -y numpy
-# Install necessary environment for Python < 3.13.
-pip install pyarrow==15.0.0 Cython wheel pytest
-# For Python 3.13, pyarrow 18.0.0 is available and requires numpy version
greater than 2.
-# pip install pyarrow==18.0.0 Cython wheel pytest
-pip install -v -e .
+pip install pyfory
```
-If the last steps fails with an error like `libarrow_python.dylib: No such
file or directory`,
-you are probably suffering from bazel's aggressive caching; the sought library
is longer at the
-temporary directory it was the last time bazel ran. To remedy this run
-
-> bazel clean --expunge
+## Quickstart
-In this situation, you might also find it fruitful to run bazel yourself
before pip:
+Here are a few examples of how to use `pyfory` for serialization.
-> bazel build -s //:cp_fory_so
+### Basic Serialization
-### Environment Requirements
+This example shows how to serialize and deserialize a simple Python object.
-- python 3.8+
+```python
+from typing import Dict
+import pyfory
-## Testing
+class SomeClass:
+ f1: "SomeClass"
+ f2: Dict[str, str]
+ f3: Dict[str, str]
-```bash
-cd python
-pytest -v -s .
+fory = pyfory.Fory(ref_tracking=True)
+fory.register_type(SomeClass, typename="example.SomeClass")
+obj = SomeClass()
+obj.f2 = {"k1": "v1", "k2": "v2"}
+obj.f1, obj.f3 = obj, obj.f2
+data = fory.serialize(obj)
+# bytes can be data serialized by other languages.
+print(fory.deserialize(data))
```
-## Code Style
+### Cross-language Serialization
-```bash
-cd python
-pip install ruff
-ruff format python
-```
+Fory excels at cross-language serialization. You can serialize data in Python
and deserialize it in another language like Java or Go, and vice-versa.
-## Debug
+Here's an example of how to serialize an object in Python and deserialize it
in Java:
-```bash
-cd python
-python setup.py develop
-```
+**Python**
-- Use `cython --cplus -a pyfory/_serialization.pyx` to produce an annotated
HTML file of the source code. Then you can
- analyze interaction between Python objects and Python's C API.
-- Read more:
<https://cython.readthedocs.io/en/latest/src/userguide/debugging.html>
+```python
+from typing import Dict
+import pyfory
-```bash
-FORY_DEBUG=true python setup.py build_ext --inplace
-# For linux
-cygdb build
-```
+class SomeClass:
+ f1: "SomeClass"
+ f2: Dict[str, str]
+ f3: Dict[str, str]
-## Debug with lldb
+fory = pyfory.Fory(ref_tracking=True)
+fory.register_type(SomeClass, typename="example.SomeClass")
+obj = SomeClass()
+obj.f2 = {"k1": "v1", "k2": "v2"}
+obj.f1, obj.f3 = obj, obj.f2
+data = fory.serialize(obj)
+# `data` can now be sent to a Java application
+```
-```bash
-lldb
-(lldb) target create -- python
-(lldb) settings set -- target.run-args "-c" "from pyfory.tests.test_serializer
import test_enum; test_enum()"
-(lldb) run
-(lldb) bt
+**Java**
+
+```java
+import org.apache.fory.*;
+import org.apache.fory.config.*;
+import java.util.*;
+
+public class ReferenceExample {
+ public static class SomeClass {
+ SomeClass f1;
+ Map<String, String> f2;
+ Map<String, String> f3;
+ }
+
+ public static void main(String[] args) {
+ Fory fory = Fory.builder().withLanguage(Language.XLANG)
+ .withRefTracking(true).build();
+ fory.register(SomeClass.class, "example.SomeClass");
+ // `bytes` would be the data received from the Python application
+ byte[] bytes = ...
+ System.out.println(fory.deserialize(bytes));
+ }
+}
```
+
+## Useful Links
+
+- **[Project Website](https://fory.apache.org)**
+- **[Documentation](https://fory.apache.org/docs/latest/python_guide/)**
+- **[GitHub Repository](https://github.com/apache/fory)**
+- **[Issue Tracker](https://github.com/apache/fory/issues)**
+- **[Slack
Channel](https://join.slack.com/t/fory-project/shared_invite/zt-36g0qouzm-kcQSvV_dtfbtBKHRwT5gsw)**
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
