{"id":9310,"library":"smithy-core","title":"Smithy Core","description":"Smithy-core is a Python library providing foundational SDK interfaces and transport-agnostic core components for implementing Smithy tooling and building service clients in Python. It is currently in a pre-alpha development stage (version 0.4.0) with all interfaces subject to change. The library is released as part of the broader Smithy Python ecosystem and receives updates frequently, as seen in its release history.","status":"active","version":"0.4.0","language":"en","source_language":"en","source_url":"https://github.com/smithy-lang/smithy-python/tree/develop/packages/smithy-core","tags":["aws","idl","code generation","sdk","client","service","pre-alpha"],"install":[{"cmd":"pip install smithy-core","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Required Python version for smithy-core.","package":"python","optional":false}],"imports":[{"note":"While `smithy-core` provides foundational interfaces and types, direct import and use by end-developers for application logic is uncommon. It primarily serves as a dependency for generated Smithy clients and tooling, meaning users typically interact with code *generated* from Smithy models, which then relies on `smithy-core`.","symbol":"SomeCoreType","correct":"from smithy_core.interfaces import SomeCoreType"}],"quickstart":{"code":"# smithy-core is primarily a foundational library for code generation.\n# End-users typically interact with clients generated from Smithy models,\n# which then use smithy-core internally.\n#\n# To get started with a generated client, you would first define a Smithy model (e.g., main.smithy):\n#\n# # main.smithy\n# $version: \"2.0\"\n# namespace com.example\n# use aws.protocols#restJson1\n#\n# service MyService {\n#   operations: [SayHello]\n# }\n#\n# operation SayHello {\n#   input: SayHelloInput,\n#   output: SayHelloOutput\n# }\n#\n# structure SayHelloInput {\n#   name: String\n# }\n#\n# structure SayHelloOutput {\n#   message: String\n# }\n#\n# Then, use the Smithy CLI to build the Python client:\n#\n# # Assuming 'smithy-build.json' is configured for Python client generation\n# smithy build\n#\n# After generation, the client would be available in a build directory,\n# and you would install and import from that generated client, not directly from smithy-core.\n#\n# Example of using a *hypothetical generated client* (not direct smithy-core usage):\n# import asyncio\n# from generated_client import MyServiceServiceClient\n#\n# async def main():\n#     client = MyServiceServiceClient()\n#     response = await client.say_hello(name='World')\n#     print(response.message)\n#\n# if __name__ == '__main__':\n#     asyncio.run(main())","lang":"python","description":"Smithy-core is a foundational library. A direct quickstart for using `smithy-core` in isolation is not typical, as it's designed to underpin generated clients rather than for direct application development. The common pattern involves defining a Smithy model, using the Smithy CLI to generate a Python client, and then interacting with that generated client. The example above illustrates the conceptual flow, showing how a generated client would be used, implicitly relying on `smithy-core`."},"warnings":[{"fix":"Users should exercise caution, anticipate frequent API changes, and avoid using it in production environments. Pinning to specific minor versions and reviewing changes carefully between updates is recommended for development use.","message":"Smithy-core is in a 'Pre-Alpha' development stage, and all of its interfaces are subject to change without prior notice. It is explicitly stated that this code generator and its clients are unstable and should not be used in production systems yet.","severity":"breaking","affected_versions":"0.0.1 - 0.4.0 (all versions to date)"},{"fix":"Focus on understanding the Smithy IDL and the client generation process. When building applications, expect to import from your *generated* client code, not directly from `smithy-core`.","message":"The `smithy-core` package is a foundational component for Smithy's Python client generation and tooling, not typically for direct application-level consumption. Developers usually interact with code generated by Smithy, which then relies on `smithy-core` internally.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"You must first define a Smithy model, configure `smithy-build.json` for Python client generation, run `smithy build` to generate the client, and then install the generated client package (e.g., `pip install ./path/to/generated-client`). After installation, you can import from the actual name of your generated client module.","cause":"This error occurs because 'generated_client' is a placeholder for a client that you need to generate from a Smithy model using the Smithy CLI and then install, or ensure its path is in your Python environment. You cannot directly import a client that hasn't been generated.","error":"ModuleNotFoundError: No module named 'generated_client'"},{"fix":"Due to the pre-alpha status and evolving interfaces, detailed debugging of `smithy-core`-related `TypeError`s often requires examining the generated client code and the specific Smithy model definitions. Ensure all required configurations and inputs for your generated client operations are provided, and that your Smithy model is valid and complete. Consult the Smithy Python GitHub repository for the latest development status and known issues.","cause":"Given `smithy-core`'s low-level and pre-alpha nature, this generic `TypeError` could arise from unexpected `None` values where iterables are expected, often due to uninitialized or missing components within the underlying generated client's interaction with `smithy-core` interfaces, reflecting the instability of early development.","error":"TypeError: argument of type 'NoneType' is not iterable"}]}