Welcome to knitlib’s documentation!

Contents:

Overview

knitlib

Travis-CI Build Status Documentation Status
'Stories in Ready'

A library designed to support the operation of varied knitting machines, mechanisms, and hacks.

Knitlib is based on projects like AYAB, PDD, and KnitterStream to control knitting machines. Knitlib features a plugin system for knitting machines and implements an API to control machines’ operation, knitting jobs and knitting patterns. The software is based on Python. There also is a Web API. Among the primary tasks is to develop plugins based on this solution to add support for more machines.

Free software: GPLv3+ license

Development Installation

pip install -r requirements.txt pip install knitlib

Documentation

Development

To run the all tests run:

tox

Installation

At the command line:

pip install knitlib

Usage

To use knitlib in a project:

import knitlib

# Search for a plugin via it's public name.
Plugin = knitlib.machine_handler.get_machine_plugin_by_id(plugin_name)
# Initalize the plugin instance
machine_instance = Plugin()
machine_instance.configure(conf={'options': 'go here'})
# Knit will block execution. If you need async execution check the callbacks configuration.
machine_instance.knit()
machine_instance.finish()

Each machine has it’s own configuration options, however the base functions are standardized in knitpat. Check the Knitpat section for more info.

Knitlib API allows for setting callbacks for certain actions that the user needs to interact with the underlying hardware. This callbacks system includes messaging, messages with blocking operations (move knob, set dial, feed yarn, etc) and progress. Default callbacks are included for CLI operation, and projects should provide their own implementations for the environment in use (knitweb, desktop UIs, etc).

Reference

Knitlib Overview

Knitlib modules

Knitlib machine handler

knitlib.machine_handler.get_active_machine_plugins_names()[source]

Returns a list of tuples of the available plugins and type.

knitlib.machine_handler.get_available_ports()[source]

Returns a list tuples of available serial ports.

knitlib.machine_handler.get_machine_plugin_by_id(machine_id, if_not_found=None)[source]

Returns a machine plugin given the machine_id class name.

knitlib.machine_handler.get_machine_types()[source]

Returns the PluginType Enum.

knitlib.machine_handler.get_machines_by_type(machine_type)[source]

Returns a list of the available plugins for a given PluginType or empty array if none found.

Knitlib Knitting Jobs

class knitlib.knitting_job.KnittingJob(plugin_class, port, callbacks_dict=None, knitpat_dict=None)[source]

A Knitting job is composed of a Machine Plugin at a certain state, a port and a knitpat file.

Knitlib Plugin API

Base Knitting Plugin

class knitlib.plugins.knitting_plugin.BaseKnittingPlugin(callbacks_dict=None, interactive_callbacks=None)[source]

A generic plugin implementing a state machine for knitting.

Subclasses inherit the basic State Machine defined in __init__.

onconfigure(e)[source]

Callback when state machine executes configure(conf={})

This state gets called to configure the plugin for knitting. It can either be called when first configuring the plugin, when an error happened and a reset is necessary.

Parameters:e – An event object holding a conf dict.
onfinish(e)[source]

Callback when state machine executes finish().

When finish() gets called, the plugin is expected to be able to restore it’s state back when configure() gets called. Finish should trigger a Process Completed notification so the user can operate accordingly.

onknit(e)[source]

Callback when state machine executes knit().

Starts the knitting process, this is the only function call that can block indefinitely, as it is called from an instance of an individual Thread, allowing for processes that require timing and/or blocking behaviour.

register_interactive_callbacks(callbacks=None)[source]

Serves to register a dict of callbacks that require interaction by the User,

Interactive callbacks serve to block operation until a human acts on them. Interactive callbacks can include physical operations (set needles, move knob, flip switch), decisions (yes/no or cancel), or simply human acknowledgement.

Parameters:callbacks – keys can be info, warning, progress, error.
set_port(portname)[source]

Sets a port name before configuration method.

static supported_config_features()[source]

Returns a JSON schema dict with the available features for the given machine plugin.

Knitpat

Knitpat is an standarized format for knitting machine files. It is based in JSON, validated via a JSON Schema and by each tool according to it’s supported features.

knitlib.knitpat.parse_dict_from_cli(cli_dict)[source]

Parses from CLI dict into a valid Knitpat.

knitlib.knitpat.parse_ustring(string_data)[source]

Parses a string into a dict and validates it.

knitlib.knitpat.validate_dict(loaded_json_data)[source]

Checks if a dict is a valid Knitpat format.

Validates if a dict, loaded from a json file, is valid according to the Knitpat scheme.

Returns:True if valid, False if not.

Contributing

Contributions are welcome, and they are greatly appreciated! Every little bit helps, and credit will always be given.

Bug reports

When reporting a bug please include:

  • Your operating system name and version.
  • Any details about your local setup that might be helpful in troubleshooting.
  • Detailed steps to reproduce the bug.

Documentation improvements

knitlib could always use more documentation, whether as part of the official knitlib docs, in docstrings, or even on the web in blog posts, articles, and such.

Feature requests, bug reports, and feedback

The best way to send feedback is to file an issue at https://github.com/fashiontec/knitlib/issues.

If you are proposing a feature:

  • Explain in detail how it would work.
  • Keep the scope as narrow as possible, to make it easier to implement.
  • Remember that this is a volunteer-driven project, and that contributions are welcome :)

Development

To set up knitlib for local development:

  1. Fork knitlib on GitHub.

  2. Clone your fork locally:

    git clone git@github.com:your_name_here/knitlib.git

  3. Create a branch for local development:

    git checkout -b name-of-your-bugfix-or-feature

    Now you can make your changes locally.

  4. When you’re done making changes, run all the checks, doc builder and spell checker with tox one command:

    tox

  5. Commit your changes and push your branch to GitHub:

    git add .
git commit -m "Your detailed description of your changes."
git push origin name-of-your-bugfix-or-feature

  6. Submit a pull request through the GitHub website.

  7. Assign some one to review the code, somebody who is familiar with the architecture. Or some of the other students involved.

  8. Handle the code changes required by the reviewer, discuss alternative ways etc.

9. Clean up, reduce commits for the entire stuff done via the PR (Squashing Commits - http://gitready.com/advanced/2009/02/10/squashing-commits-with-rebase.html) 11. Ensure it runs tests. 10. Once the PR (Pull Request) is green (reviewer says OK or LGTM), merge the PR and delete the branch.

Pull Request Guidelines

If you need some code review or feedback while you’re developing the code just make the pull request.

For merging, you should:

  1. Include passing tests (run tox) [1].
  2. Update documentation when there’s new API, functionality etc.
  3. Add a note to CHANGELOG.rst about the changes.
  4. Add yourself to AUTHORS.rst.
[1]

If you don’t have all the necessary python versions available locally you can rely on Travis - it will run the tests for each change you add in the pull request.

It will be slower though ...

Tips

  • To run a subset of tests:

    tox -e envname -- py.test -k test_myfeature

  • To run all the test environments in parallel (you need to pip install detox):

    detox

  • Please check the Google Python coding guidelines, it has good advices in order to write properly structured code.

Authors

AYAB Authors

  • Christian Obersteiner
  • Andreas Müller

PDD Authors

  • Steve Conklin

Changelog

0.0.1 (2015-05-15

  • First release on PyPI.

Indices and tables