micro-components-py 0.2.1

Lightweight library to create components that can automagically be used as either CLI or as native classes in other programming languages

Micro Components for Python

Lightweight library to create components that can automagically be used as either CLI or as native classes in other programming languages

The same package is available for Node. Check it out if you want Python and Node components talking to each other!

Goals & Design

Often times, which programming language I pick is predetermined by technical requirements and the resources available in that language. In many cases I have to use a mixture of nodejs, Python, and bash scripts, and they all have to talk to each other.

The intent of this library is to provide a utility class turning Singleton classes into command line interfaces and providing an intuitive class interface between different programming languages. Since a lot of the code I produce is either Node or Python, I started by creating components for those two languages.

The beauty of this is that components have a simple JSON interface to talk to each other, irregardless of the programming language. Any other language implementing the Component interface can now be imported as if it were a native class.

Installation

In your terminal run:

$ pip install micro-components-py

Usage

To run a component from the terminal, you need the following structure at minimum:

from micro_components import Component

class TaskRunner(Component):
	name = 'task_runner'

	def run(task_id):
		return { 'task_id': task_id, 'status': 'running' }

TaskRunner.export_as_cli();

To then be able to run one of the following commands from your terminal:

$ taskrunner.py run 95
# output: { "task_id": 95, "status": "running"  }

$ taskrunner.py run --task-id="hello world"
# output: { "task_id": "hello world", "status": "running"  }

$ taskrunner.py run --task-id="[5,9,true]"
# output: { "task_id": [5, 9, true], "status": "running"  }

Example of Python and Node components interacting:

Consider this JavaScript component called task_logger.js:

const fs = require('fs');
const { Component } = require('micro-components-js');

const TaskLogger = Component({
	name: 'task_logger',

	log(infos) {
		fs.writeFileSync('log.json', infos);
	}
});

TaskLogger.export_to_cli();

We can now use TaskLogger from within our task_runner.py code:

from micro_components import Component
TaskLogger = Component.from_cli('./task_logger.js')

class TaskRunner(Component):
	name = 'task_runner'

	run(task_id):
		result = { 'task_id': task_id, 'status': 'running' }
		TaskLogger.log(result)
		return result
	
TaskRunner.export_as_cli()

Creation from Terminal

You can use the micro-components CLI to create a component like so:

In your terminal:

$ micro-components create "My Component"

This will create a skeleton component file in your current directory.

Naming Convention

Components have a snake_cased filename and hold the same name as a property at minimum:

from micro-components import Component

class SomeComponent(Component):
	name = 'some_component'

Class names follow usual conventions of StartCase.

from components.intent_matcher import IntentMatcher

Exporting

You can use one of two export methods to either import components as modules "inline" or call their methods from the command line.

As CLI

To turn a component into a CLI, use the command export_as_cli():

SomeComponent.export_as_cli()

Manual Creation

If you create your component by hand, make sure your file is executable by adding a Shebang at the top of it…

#!/usr/bin/env python3

…and by giving it execution permissions (in your terminal)…

$ chmod +x ./components/some_component.py

…to then run the methods:

$ ./components/some_component.py fetch_data "parameter" 15 "{ \"sub-param\": \"value\" }"

The Component class will automagically look at the parameter defaults of your component's methods and try to parse parameters passed through the CLI accordingly.

Consider the following example component:

class RecipeFetcher(Component):
	name = 'recipe_fetcher'
	counts = 0

	def get_ingredients(ingredient_name, max_count=10, normalize=True, options={}):
		...

RecipeFetcher.export_as_cli();

We pass the following arguments via CLI:

$ ./components/recipe_fetcher.py get_ingredients "Onion Soup" 15 false "{ \"pepper\": false }"

The component class will automatically parse 15, false, and the passed JSON string as JSON and use the true datatypes.

Named Arguments

You can pass named arguments by prefixing the parameter names with two hyphens instead:

$ /components/recipe_fetcher.py get_ingredients --ingredient_name "Mangosteen" --normalize=1

Properties for the component class can be passed the same way. Arguments that don't match method names will be applied as properties. Any hyphens will be replaced by underscores, meaning --user-id will be read as user_id.

$ /components/recipe_fetcher.py get_ingredients --user-id=1337 --ingredient_name="Capers"

Method Chaining

Methods can be chained using the chain notation (beware that spacing is crucial):

$ /components/recipe_fetcher.py [ load_ingredients "all" , get_ingredients "Pepper" 12 ]

will first run RecipeFetcher.load_ingredients("all"), then RecipeFetcher.get_ingredients("Pepper", 12) and return a dictionary of results for each execution.

Caching

Before using any of the built-in caching functionality, make sure you have a directory called data/caches to store those in.

TODO: add documentation for caching decorators

A JSON cache will be auto-generated in /data/caches/<component_name>.cache.json.

API

Components provide the following interface:

Events

Components and utility classes all emit events that can be listened to. You can attach event listeners using the on method.

RecipeFetcher.on('spawn', lambda self: print('RecipeFetcher loaded.') or self)

The following events are available on every component:

Event Name	Triggered …	passed arguments
spawn	once on initialization	self instance, needs to be returned back
init	every time the component is being updated using ComponentName.init(...)	self instance, options object
cache	every time a method's cache is being hit	key used to retrieve value from cache
call_from_cli	once upon calling the component from the command line	command is the called method, args the passed arguments, verbose to turn console output on/off

To trigger (e.g. your own) events, use the trigger method:

RecipeFetcher.trigger('recipe_outdated', ['some', 'arguments'])

If the event handler returned something, it will be passed through trigger as return value.

new_recipe = RecipeFetcher.trigger('recipe_outdated', [old_recipe])

---

Properties

You can access non-callable properties from the CLI using the component module's built-in get and set methods in your terminal:

$ ./components/recipe_fetcher.py get counts 	# returns 1

$ ./components/recipe_fetcher.py set counts 3

---

Shortcuts

All components automatically get a help method, so if uncertain about properties run ./components/recipe_fetcher.py help. All methods automatically get a --help directive, so if uncertain about parameters run ./components/recipe_fetcher.py get_ingredients --help.

Integration

You can call components written in Javascript from Python and vice-versa as if they were written in the same language using the Component module.

Our previous RecipeFetcher example was written in Javascript, but now we want to use it in Python. Here's how:

from micro_components import Component

RecipeFetcher = Component.from_cli('./components/recipe_fetcher.js');
ingredients = RecipeFetcher.get_ingredients("Onion Soup", 15, False, { 'pepper': False })

To access properties, use the built-in property getters and setters (see "Properties"), like so:

from micro_components import Component

RecipeFetcher = Component.from_cli('./components/recipe_fetcher.py')
counts = RecipeFetcher.get("counts")

Testing

This package comes with a set of standard unittest cases located in [tests/test_micro-components.py][]

Run them using:

$ pytest

or

$ python3 ./tests/test_micro-components.py

Examples

Checkout the components folder in the repo for some examples. The CLI used to create component templates for example is a component itself.

License

MIT License