Providers¶
This document covers all aspects of creating providers including the semantics of the file structure and dependencies. For writing hooks which are contained within providers, check out the writing hooks documents for python and declarative hooks.
As a recap, providers
are collections of hooks and / or tackle files that import / call additional hooks. They can be stored remotely in a git repository and then imported / ran from tackle files or called directly from the command line. For more information about tackle structure, check out the project structure docs.
Basic File Structure¶
A provider either needs to have: - A tackle file
├── hooks
│ ├── hooks.py
│ └── hooks.yaml
└── tackle.yaml
Quick Start¶
Since tackle box is a code generator, it makes sense for it to be able to generate the boilerplate to create providers. The quickest way to do that is with the tackle-provider
provider which can be run as:
tackle sudoblockio/tackle-provider
The provider will then go through a number of configuration options such as:
- What type of license (ie Apache vs MIT vs closed source)
- Types of tests (unittest vs pytest)
- Intention of the provider (code generator vs utility)
Using this provider one can create a functional provider in minutes that when pushed to github can be called with tackle <your org>/<your repo>
.
Configuration Options¶
Requirements¶
Each provider can have its own pip requirements which when the provider is imported / called are automatically installed to support the execution of hooks. Requirements are located at the base of the provider as in the following directory structure:
├── hooks
│ └── hooks.py
└── requirements.txt
Autogenerated Docs¶
Docs are automatically generated for any hooks located within the native providers directory. The docs are generated by a tackle file located in the /docs
directory in the source and uses the provider_docs hook to extract metadata about each hook and render a set of templates. Additional metadata for each provider is located in a .tackle.meta.yaml
file per the following directory structure.
├── tackle.yaml
└── .tackle.meta.yaml
The .tackle.meta.yaml
is itself a tackle file so can contain hooks that can read other files (ie test fixtures or fields within the same file). The structure is:
name: Name of hook (Required)
description: Description of hook (Required)
examples: # Optional
- name: "[hook_name](hook_name.md)"
description: Description of hook
content: |
# A yaml string as input example
stuff: things
a key->: hook_name stuff
output: |
stuff: things
a key: things
hook_examples:
hook_name: # Key must match hook_name
- description: Description of hook
content: |
# A yaml string as input example
stuff: things
a key->: hook_name stuff
output: |
stuff: things
a key: things
TODO: Document how to create docs for a third party provider
See examples in source for further information.