Skip to content

Commit 596847c

Browse files
esafakesafak
committed
docs: Improve pyfory PyPI documentation
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`.
1 parent 0922ec7 commit 596847c

2 files changed

Lines changed: 154 additions & 50 deletions

File tree

‎python/CONTRIBUTING.md‎

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
# Contributing to Apache Fory Python
2+
3+
This document provides instructions for building and testing the `pyfory` package.
4+
5+
## Building
6+
7+
```bash
8+
cd python
9+
# Uninstall numpy first so that when we install pyarrow, it will install the correct numpy version automatically.
10+
# For Python versions less than 3.13, numpy 2 is not currently supported.
11+
pip uninstall -y numpy
12+
# Install necessary environment for Python < 3.13.
13+
pip install pyarrow==15.0.0 Cython wheel pytest
14+
# For Python 3.13, pyarrow 18.0.0 is available and requires numpy version greater than 2.
15+
# pip install pyarrow==18.0.0 Cython wheel pytest
16+
pip install -v -e .
17+
```
18+
19+
If the last steps fails with an error like `libarrow_python.dylib: No such file or directory`,
20+
you are probably suffering from bazel's aggressive caching; the sought library is longer at the
21+
temporary directory it was the last time bazel ran. To remedy this run
22+
23+
> bazel clean --expunge
24+
25+
In this situation, you might also find it fruitful to run bazel yourself before pip:
26+
27+
> bazel build -s //:cp_fory_so
28+
29+
### Environment Requirements
30+
31+
- python 3.8+
32+
33+
## Testing
34+
35+
```bash
36+
cd python
37+
pytest -v -s .
38+
```
39+
40+
## Formatting
41+
42+
```bash
43+
cd python
44+
pip install ruff
45+
ruff format python
46+
```
47+
48+
## Debugging
49+
50+
```bash
51+
cd python
52+
python setup.py develop
53+
```
54+
55+
- Use `cython --cplus -a pyfory/_serialization.pyx` to produce an annotated HTML file of the source code. Then you can
56+
analyze interaction between Python objects and Python's C API.
57+
- Read more: <https://cython.readthedocs.io/en/latest/src/userguide/debugging.html>
58+
59+
```bash
60+
FORY_DEBUG=true python setup.py build_ext --inplace
61+
# For linux
62+
cygdb build
63+
```
64+
65+
### Debugging with lldb
66+
67+
```bash
68+
lldb
69+
(lldb) target create -- python
70+
(lldb) settings set -- target.run-args "-c" "from pyfory.tests.test_serializer import test_enum; test_enum()"
71+
(lldb) run
72+
(lldb) bt
73+
```

‎python/README.md‎

Lines changed: 81 additions & 50 deletions
Original file line numberDiff line numberDiff line change
@@ -1,73 +1,104 @@
11
# Apache Fory™ Python
22

3-
Fory is a blazingly-fast multi-language serialization framework powered by just-in-time compilation and zero-copy.
3+
[![Build Status](https://img.shields.io/github/actions/workflow/status/apache/fory/ci.yml?branch=main&style=for-the-badge&label=GITHUB%20ACTIONS&logo=github)](https://github.com/apache/fory/actions/workflows/ci.yml)
4+
[![PyPI](https://img.shields.io/pypi/v/pyfory.svg?logo=PyPI)](https://pypi.org/project/pyfory/)
5+
[![Slack Channel](https://img.shields.io/badge/slack-join-3f0e40?logo=slack&style=for-the-badge)](https://join.slack.com/t/fory-project/shared_invite/zt-36g0qouzm-kcQSvV_dtfbtBKHRwT5gsw)
6+
[![X](https://img.shields.io/badge/@ApacheFory-follow-blue?logo=x&style=for-the-badge)](https://x.com/ApacheFory)
47

5-
## Build Fory Python
8+
**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.
9+
10+
This package provides the Python bindings for Apache Fory.
11+
12+
## Installation
13+
14+
You can install `pyfory` using pip:
615

716
```bash
8-
cd python
9-
# Uninstall numpy first so that when we install pyarrow, it will install the correct numpy version automatically.
10-
# For Python versions less than 3.13, numpy 2 is not currently supported.
11-
pip uninstall -y numpy
12-
# Install necessary environment for Python < 3.13.
13-
pip install pyarrow==15.0.0 Cython wheel pytest
14-
# For Python 3.13, pyarrow 18.0.0 is available and requires numpy version greater than 2.
15-
# pip install pyarrow==18.0.0 Cython wheel pytest
16-
pip install -v -e .
17+
pip install pyfory
1718
```
1819

19-
If the last steps fails with an error like `libarrow_python.dylib: No such file or directory`,
20-
you are probably suffering from bazel's aggressive caching; the sought library is longer at the
21-
temporary directory it was the last time bazel ran. To remedy this run
22-
23-
> bazel clean --expunge
20+
## Quickstart
2421

25-
In this situation, you might also find it fruitful to run bazel yourself before pip:
22+
Here are a few examples of how to use `pyfory` for serialization.
2623

27-
> bazel build -s //:cp_fory_so
24+
### Basic Serialization
2825

29-
### Environment Requirements
26+
This example shows how to serialize and deserialize a simple Python object.
3027

31-
- python 3.8+
28+
```python
29+
from typing import Dict
30+
import pyfory
3231

33-
## Testing
32+
class SomeClass:
33+
f1: "SomeClass"
34+
f2: Dict[str, str]
35+
f3: Dict[str, str]
3436

35-
```bash
36-
cd python
37-
pytest -v -s .
37+
fory = pyfory.Fory(ref_tracking=True)
38+
fory.register_type(SomeClass, typename="example.SomeClass")
39+
obj = SomeClass()
40+
obj.f2 = {"k1": "v1", "k2": "v2"}
41+
obj.f1, obj.f3 = obj, obj.f2
42+
data = fory.serialize(obj)
43+
# bytes can be data serialized by other languages.
44+
print(fory.deserialize(data))
3845
```
3946

40-
## Code Style
47+
### Cross-language Serialization
4148

42-
```bash
43-
cd python
44-
pip install ruff
45-
ruff format python
46-
```
49+
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.
4750

48-
## Debug
51+
Here's an example of how to serialize an object in Python and deserialize it in Java:
4952

50-
```bash
51-
cd python
52-
python setup.py develop
53-
```
53+
**Python**
5454

55-
- Use `cython --cplus -a pyfory/_serialization.pyx` to produce an annotated HTML file of the source code. Then you can
56-
analyze interaction between Python objects and Python's C API.
57-
- Read more: <https://cython.readthedocs.io/en/latest/src/userguide/debugging.html>
55+
```python
56+
from typing import Dict
57+
import pyfory
5858

59-
```bash
60-
FORY_DEBUG=true python setup.py build_ext --inplace
61-
# For linux
62-
cygdb build
63-
```
59+
class SomeClass:
60+
f1: "SomeClass"
61+
f2: Dict[str, str]
62+
f3: Dict[str, str]
6463

65-
## Debug with lldb
64+
fory = pyfory.Fory(ref_tracking=True)
65+
fory.register_type(SomeClass, typename="example.SomeClass")
66+
obj = SomeClass()
67+
obj.f2 = {"k1": "v1", "k2": "v2"}
68+
obj.f1, obj.f3 = obj, obj.f2
69+
data = fory.serialize(obj)
70+
# `data` can now be sent to a Java application
71+
```
6672

67-
```bash
68-
lldb
69-
(lldb) target create -- python
70-
(lldb) settings set -- target.run-args "-c" "from pyfory.tests.test_serializer import test_enum; test_enum()"
71-
(lldb) run
72-
(lldb) bt
73+
**Java**
74+
75+
```java
76+
import org.apache.fory.*;
77+
import org.apache.fory.config.*;
78+
import java.util.*;
79+
80+
public class ReferenceExample {
81+
public static class SomeClass {
82+
SomeClass f1;
83+
Map<String, String> f2;
84+
Map<String, String> f3;
85+
}
86+
87+
public static void main(String[] args) {
88+
Fory fory = Fory.builder().withLanguage(Language.XLANG)
89+
.withRefTracking(true).build();
90+
fory.register(SomeClass.class, "example.SomeClass");
91+
// `bytes` would be the data received from the Python application
92+
byte[] bytes = ...
93+
System.out.println(fory.deserialize(bytes));
94+
}
95+
}
7396
```
97+
98+
## Useful Links
99+
100+
- **[Project Website](https://fory.apache.org)**
101+
- **[Documentation](https://fory.apache.org/docs/latest/python_guide/)**
102+
- **[GitHub Repository](https://github.com/apache/fory)**
103+
- **[Issue Tracker](https://github.com/apache/fory/issues)**
104+
- **[Slack Channel](https://join.slack.com/t/fory-project/shared_invite/zt-36g0qouzm-kcQSvV_dtfbtBKHRwT5gsw)**

0 commit comments

Comments
 (0)