updated readme

jhnnsrs · Jan 13, 2023 · 3eccc82 · 3eccc82
1 parent 45061f0
commit 3eccc82
Showing 1 changed file with 72 additions and 80 deletions.
diff --git a/README.md b/README.md
@@ -8,43 +8,71 @@
 [![PyPI status](https://img.shields.io/pypi/status/turms.svg)](https://pypi.python.org/pypi/turms/)
 [![PyPI download month](https://img.shields.io/pypi/dm/turms.svg)](https://pypi.python.org/pypi/turms/)
 
-## Inspiration
+## Goal
 
-Turms is a pure python implementation following the awesome graphql-codegen library with a similar extensible design.
-It makes heavy use of pydantic and its serialization capablities and provides fully typed querys, mutations and subscriptions
+Turms is a `graphql-codegen` inspired code generator for python that generates typed and serializable python code from your graphql schema and documents. Just define your query in standard graphql syntax and let turms create fully typed queries/mutation and subscriptions, that you can use in your favourite IDE.
 
-## Supports
+Turms allows you to easily generate both server-side and client-side code for your GraphQL API.
 
-Schema Generation
+### Schema (Server) Generation:
+
+Can generate the following types from your graphql SDL schema:
 
 - Enums
 - Inputs
 - Objects
+- Scalars
+- Directives
+
+Sepcific generation supported for:
+
+- [x] Strawberry
+- [ ] Graphene
+
+### Documents (Client) Generation
 
-Documents Generation
+Can generate the following pydantic models from your graphql documents:
 
+- Enums
+- Inputs
+- Scalars
 - Fragments
 - Operations
 
 ## Features
 
-- minimal, but fully documented code generation
-- agnostic of graphql transport (gql, and rath examples)
-- Autocollapsing operation functions
-- Specify type mixins, configuration
-- full support type hints for variables (Pylance)
+- Fully typed, fully documented code generation
+- Schema and Document based code generation
+- Compatible with popular graphql libraries (strawberry, gql, rath, etc.)
+- Support for custom scalars, custom directives, ...
+- Powerful plugin system (e.g. custom Linting, custom formatting, etc.)
+- Operation functions like query, mutation, subscription (e.g. `data= get_capsules()`)
 - Compliant with graphl-config
-- Support for custom scalars
+- Code migration support (trying to merge updates into existing code)
 
 ## Installation
 
 ```bash
 pip install turms
 ```
 
+turms is a pure development library and will not introduce any dependency on itself into your
+code, so we recommend installing turms as a development dependency.
+
+```bash
+poetry add -D turms
+
+```
+
+As of now turms only supports python 3.9 and higher (as we rely on ast unparsing)
+
 ## Configuration
 
-Turms configuration is compliant with the graphql-config specification, allowing interoperability with other frameworks.
+Turms relies on and complies with [graphql-config](https://www.graphql-config.com/docs/user/user-introduction) and searches your current working dir for the graphql-config file.
+
+### Document based generation
+
+Based on pydantic models
 
 ```yaml
 projects:
@@ -54,79 +82,56 @@ projects:
     extensions:
       turms: # path for configuration for turms
         out_dir: examples/api
-        stylers:
-          - type: turms.stylers.capitalize.CapitalizeStyler
-          - type: turms.stylers.snake_case.SnakeCaseStyler
-        plugins:
+        plugins: # path for plugin configuration
           - type: turms.plugins.enums.EnumsPlugin
           - type: turms.plugins.inputs.InputsPlugin
           - type: turms.plugins.fragments.FragmentsPlugin
-          - type: turms.plugins.operations.OperationsPlugin
+          - type: turms.plugins.operation.OperationsPlugin
           - type: turms.plugins.funcs.FuncsPlugin
         processors:
-          - type: turms.processors.black.BlackProcessor
-          - type: turms.processors.isort.IsortProcessor
+          - type: turms.processor.black.BlackProcessor
+          - type: turms.processor.isort.IsortProcessor
         scalar_definitions:
           uuid: str
           timestamptz: str
           Date: str
 ```
 
-## Run
-
-```bash
-turms gen
-```
-
-Turms configuration is based on plugins that can be configured in the graphql.config. There exist three major classes:
-
-### Stylers
-
-Stylers are responsible for applying different styles to the class names and field names (e.g. snakecasing of graphqls pascalcase),
-they are chained in order of notation in the graphql config (they receive the output of the last styler). Turms takes care of automatically
-aliasing these names if they are not the same as the graphql style)
-
-### Plugins
-
-Plugins are the generators of code, that traverse through the direcotry and ad new ast nodes to the global tree. Examplary pluings are:
-
-- turms.plugins.enums.EnumsPlugin
-- turms.plugins.inputs.InputsPlugin
-- turms.plugins.fragments.FragmentsPlugin
-- turms.plugins.operations.OperationsPlugin
-- turms.plugins.funcs.FuncsPlugin
-
-## Parsers
+### Schema based generation
 
-Parsers take the generated python.AST, and can parse this code. (e.g enabling polyfills for different python versions)
-Includes Parsers are
+Based on strawberry models
 
-- turms.parsers.polyfill.PolyfillParser (only working for python 3.7)
-
-## Processors
-
-Processors take the generated code (already a string), and can parse this code. (e.g. black processor for enforcing black style formatting) or isort of sorting imports.
-Includes Processors are
-
-- turms.processor.black.BlackProcessor
-- turms.processor.isort.IsortProcessor
-
-## Usage
-
-Open your workspace (create a virtual env), in the root folder
-
-```bash
-turms init
+```yaml
+projects:
+  default:
+    schema: beasts.graphql
+    extensions:
+      turms:
+        skip_forwards: true
+        out_dir: api
+        stylers:
+          - type: turms.stylers.capitalize.CapitalizeStyler
+          - type: turms.stylers.snake_case.SnakeCaseStyler
+        plugins:
+          - type: turms.plugins.strawberry.StrawberryPlugin # generates a strawberry schema
+        processors:
+          - type: turms.processors.disclaimer.DisclaimerProcessor
+          - type: turms.processors.black.BlackProcessor
+          - type: turms.processors.isort.IsortProcessor
+          - type: turms.processors.merge.MergeProcessor # merges the formated schema with already defined functions
+        scalar_definitions:
+          uuid: str
+          _Any: typing.Any
 ```
 
-This creates a graphql-config compliant configuration file in the working directory, edit this to reflect your settings (see Configuration)
+### Usage
+
+Once you have configured turms you can generate your code by running
 
 ```bash
 turms gen
 ```
 
-Generate beautifully typed Operations, Enums,...
-
 ### Why Turms
 
 In Etruscan religion, Turms (usually written as 𐌕𐌖𐌓𐌌𐌑 Turmś in the Etruscan alphabet) was the equivalent of Roman Mercury and Greek Hermes, both gods of trade and the **messenger** god between people and gods.
@@ -137,17 +142,4 @@ Turms does _not_ come with a default transport layer but if you are searching fo
 
 ## Examples
 
-This github repository also contains an example graphql.config.yaml with the public SpaceX api, as well as a sample of the generated api.
-
-## Experimental
-
-```bash
-turms watch $PROJECT_NAME
-```
-
-Turms watch is able to automatically monitor your graphql folder for changes and autogenerate the api on save again.
-Requires additional dependency for watchdog
-
-```bash
-pip install turms[watch]
-```
+This github repository also contains some examples on how to use turms with popular libraries in the graphql ecosystem.