Registry / serialization / stone
library3.5.4pypypi✓ verified 23d ago

Stone is an interface description language (IDL) and a suite of tools for defining APIs and generating client/server code in various languages. It is primarily used by Dropbox for its API development. The current version is 3.3.9, and it maintains an active release cadence with frequent patch updates and occasional minor feature additions.

pip install stone
INSTALL
IMPORT
SIG · STONE
S
stone
serializationpythonv3.5.4
Install
2.0s avg
Import
Disk
20MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v3.3.9 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 21.7MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 2.0s · import 0.000s · 22MB
20MB installed
● package 20MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

parse_stone_grammar
from stone.frontend.stone_parser import parse_stone_grammar
from stone.frontend.stone_parser import parse_stone_grammar

This quickstart demonstrates how to programmatically parse a simple Stone IDL specification using the `stone` library, accessing its Intermediate Representation (IR). It creates a temporary '.stone' file, parses it, and prints details about the defined namespace, structs, and routes. It does not perform actual code generation to keep the example concise and runnable without side effects.

import os from stone.frontend.stone_parser import parse_stone_grammar from stone.ir import Api # 1. Define a simple Stone spec content stone_spec_content = """ namespace example struct User { id String name String } route greet(name: String): User "Greets a user." """ # Create a temporary .stone file for parsing temp_stone_file = "temp_spec.stone" with open(temp_stone_file, "w") as f: f.write(stone_spec_content) try: # 2. Parse the Stone spec file(s) # parse_stone_grammar expects a list of file paths api = parse_stone_grammar([temp_stone_file]) # 3. Access the parsed Intermediate Representation (IR) example_namespace = api.namespaces.get('example') if example_namespace: print("Parsed API Namespace:", example_namespace.name) print("Parsed API Structs:", [s.name for s in example_namespace.data_types if s.is_struct]) print("Parsed API Routes:", [r.name for r in example_namespace.routes]) else: print("Namespace 'example' not found in parsed API.") # For full code generation, you would then instantiate a backend # (e.g., PythonResourceBackend) with the 'api' object and call its 'generate' method. except Exception as e: print(f"Error during Stone processing: {e}") finally: # Clean up temporary file if os.path.exists(temp_stone_file): os.remove(temp_stone_file)
stone --version
Debug
Known issues
gotchaStone is an IDL compiler for *generating* client/server code, not a client library for directly making API calls. Users define an API in '.stone' files, then use Stone (typically via its CLI) to generate language-specific code (e.g., Python, Swift, TypeScript) which is then used for API interaction.
fix
Understand Stone's role as a code generation tool. Use the generated client code for API interactions, not the `stone` library itself.
affects: All versions
breakingChanges in route ordering logic and `ApiRoute` hashing/sorting (e.g., in v3.3.0 and v3.3.9) were introduced to provide stable, deterministic output from code generation. However, this might lead to changes in generated file content or order if your previous build processes implicitly relied on non-deterministic ordering, potentially affecting diffs in version control or build pipelines.
fix
Review generated code diffs after updating Stone. Ensure your build systems are resilient to potential reordering of generated elements. If relying on stable output, use Stone v3.3.9 or newer and ensure generated files are committed or cached appropriately.
affects: >=3.3.0
deprecatedThe `distutils` module, which was deprecated in Python 3.10 and removed in 3.12, was replaced by `setuptools.distutils` in `stone` v3.3.7. If you have custom build scripts or integrations that directly accessed `stone`'s internal setup process and relied on `distutils` directly, this change might affect you.
fix
Ensure your environment uses Python 3.10 or older if you need `distutils`. For `stone` v3.3.7+, any custom build logic interacting with Stone's setup should adapt to use `setuptools` based mechanisms or avoid direct interaction with internal build components.
affects: >=3.3.7
Upgrade
Version history
3.5.4latest on PyPI · released Aug 3, 2026
Audit
Dependencies

No dependency data recorded yet.

Agent activity
29 hits · last 30 days
node
24
OpenAI (training)
1
Resources
stone — pip install stone · libregistry