{"id":3819,"library":"stone","title":"Stone IDL Compiler","description":"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.","status":"active","version":"3.3.9","language":"en","source_language":"en","source_url":"https://github.com/dropbox/stone","tags":["idl","code-generation","api-design","dropbox"],"install":[{"cmd":"pip install stone","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"note":"Primary entry point for parsing .stone files programmatically.","symbol":"parse_stone_grammar","correct":"from stone.frontend.stone_parser import parse_stone_grammar"},{"note":"Represents the Intermediate Representation (IR) of the parsed Stone API definition.","symbol":"Api","correct":"from stone.ir import Api"},{"note":"An example backend for generating Python resource code from a Stone API.","symbol":"PythonResourceBackend","correct":"from stone.backends.python_rsrc import PythonResourceBackend"}],"quickstart":{"code":"import os\nfrom stone.frontend.stone_parser import parse_stone_grammar\nfrom stone.ir import Api\n\n# 1. Define a simple Stone spec content\nstone_spec_content = \"\"\"\nnamespace example\n\nstruct User {\n    id String\n    name String\n}\n\nroute greet(name: String): User\n    \"Greets a user.\"\n\"\"\"\n\n# Create a temporary .stone file for parsing\ntemp_stone_file = \"temp_spec.stone\"\nwith open(temp_stone_file, \"w\") as f:\n    f.write(stone_spec_content)\n\ntry:\n    # 2. Parse the Stone spec file(s)\n    # parse_stone_grammar expects a list of file paths\n    api = parse_stone_grammar([temp_stone_file])\n\n    # 3. Access the parsed Intermediate Representation (IR)\n    example_namespace = api.namespaces.get('example')\n    if example_namespace:\n        print(\"Parsed API Namespace:\", example_namespace.name)\n        print(\"Parsed API Structs:\", [s.name for s in example_namespace.data_types if s.is_struct])\n        print(\"Parsed API Routes:\", [r.name for r in example_namespace.routes])\n    else:\n        print(\"Namespace 'example' not found in parsed API.\")\n\n    # For full code generation, you would then instantiate a backend\n    # (e.g., PythonResourceBackend) with the 'api' object and call its 'generate' method.\n\nexcept Exception as e:\n    print(f\"Error during Stone processing: {e}\")\nfinally:\n    # Clean up temporary file\n    if os.path.exists(temp_stone_file):\n        os.remove(temp_stone_file)\n","lang":"python","description":"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."},"warnings":[{"fix":"Understand Stone's role as a code generation tool. Use the generated client code for API interactions, not the `stone` library itself.","message":"Stone 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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"Changes 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.","severity":"breaking","affected_versions":">=3.3.0"},{"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.","message":"The `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.","severity":"deprecated","affected_versions":">=3.3.7"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}