typebuf 0.1.4
Dead simple way to define shared type definitions between applications
License: Apache-2.0
Requires Python: >=3.9,<4.0

# TypeBuf

[![Downloads](https://static.pepy.tech/personalized-badge/typebuf?period=total&units=international_system&left_color=grey&right_color=brightgreen&left_text=Installs)](https://pepy.tech/project/typebuf)
[![PyPI version](https://badge.fury.io/py/typebuf.svg)](https://badge.fury.io/py/typebuf)
[![CircleCI](https://circleci.com/gh/shanahanjrs/typebuf/tree/master.svg?style=svg)](https://circleci.com/gh/shanahanjrs/typebuf/tree/master)
[![codecov](https://codecov.io/gh/shanahanjrs/typebuf/branch/master/graph/badge.svg?token=9J1OCNHSZF)](https://codecov.io/gh/shanahanjrs/typebuf)
[![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=shanahanjrs_typebuf&metric=sqale_rating)](https://sonarcloud.io/summary/new_code?id=shanahanjrs_typebuf)
[![Reliability Rating](https://sonarcloud.io/api/project_badges/measure?project=shanahanjrs_typebuf&metric=reliability_rating)](https://sonarcloud.io/summary/new_code?id=shanahanjrs_typebuf)

---

### Dead simple way to create shared type definitions between applications

- Other tools have too much setup? Too much boilerplate? Do too much "magic"? Just:
  - Define your Types in `types.yaml`
  - Run TypeBuf: `$ typebuf compile -f types.yaml -l python -l typescript`

## Install

`pip install typebuf`

`poetry add --dev typebuf`


## Quickstart

1. Create a file called `types.yaml`, it can be anywhere in your project repo
 

2. Add the following lines to the newly created file:

```
---
typedefs:
  - typename: User
    imports:
      python:
        - 'from typing import Optional'
    fields:
      - name: first_name
        type: string
      - name: age
        type: int
        optional: true
```


3. Now call TypeBuf with: `$ typebuf compile -l python -l typescript`


4. You now have two new files, one called `user.py` and one called `user.ts` that can you use for 
    things like data serialization/deserialization, validation, subclassing, etc

Generated Python:
```python
"""
User type definition file generated by TypeBuf
Note: Any changes made to this file will be overwritten
      during next compilation
"""

from typing import Optional


class User:
    first_name: str
    age: Optional[int]
```

Generated TypeScript:

```typescript
/**
 * User type definition file generated by TypeBuf
 * Note: Any changes made to this file will be overwritten
 *       during next compilation
 */

interface User {
  first_name: string;
  age?: number;
}
```


> Note: So far only Python and TypeScript are supported. More languages coming soon!


## Demo

> Here's a quick demo of me using TypeBuf 0.1.1. First I show the contents of the _types.yaml_ file
> then I generate Python and TypeScript source code and show the contents of the new files

[![asciicast](https://asciinema.org/a/KRGKPMQ1HCd3OtwJbLvHYWUlJ.svg)](https://asciinema.org/a/KRGKPMQ1HCd3OtwJbLvHYWUlJ)


## Documentation

- Inside _types.yaml_ there is an array called `typedefs`. This is where you add your shared type definitions
- Each type can have the following fields (required fields in **bold**):
  - **typename**: _string_
  - imports: _map[string, array[str]]_
  - **fields**: _array[Field]_
    - A `Field` has the following attributes:
      - **name**: _string_
      - **type**: _string_
      - optional: _boolean_

- In a type definition you can also specify custom/required _imports_ for any depedencies your classes may need:
  - ```
    typedefs:
      - typename: Address
        imports:
          python:
            - 'from mymodule.user import User'
            - 'from typing import Optional'
          typescript:
            - 'import { User } from "./User";'
        fields:
          - ...,
    ```