My other projects use black for code formatting, so I think I'd like to use it here as well, but I haven't been doing so yet. Setting it up in github actions would make sure I actually do it. :)

Currently, we have a (somewhat simplistic) parser for written instructions that generates charts, but we'd like to be able to also generate written instructions from charts. One step for this would be reading charts out of spreadsheets or other formats. I'm not actually entirely sure how this would work, as a typical chart includes colours and stuff that wouldn't necessarily be seen in a .csv export. But let's start with the easiest part of the problem and see if we can at least read symbols from a .csv file and get them into some sort of Chart data structure for further manipulation.

In #22 we got a notebook version of my sleeve decrease example. We should probably link it somewhere in the written docs so that people can find it and download it and change the values for their own sleeve calculations.

An update broke the sleeve example -- @ben-hampson has a fix for the markdown doc in #27 but we'll want to make sure that https://github.com/terriko/pyknit/blob/main/documentation/SleeveDecreases.ipynb is updated as well.

@ben-hampson found a doc bug in #18 that definitely wouldn't have happened if I had doctests, so this bug is a reminder that it wouldn't be a bad idea to set up Sphinx Doctests and then automatically build the documentation. (And maybe get it pushed to readthedocs?)

Currently the docs are in Markdown but I'm happy to switch to RestructuredText if that makes this easier.

I did the sleeve example on the command line, but it could just as easily have been done in jupyter. It would be nice to have an .ipynb file that allows users to load the code and modify it to suit their own sleeve decrease needs.

In the setup, the first two lines are:

virtualenv -p python 3.8 venv-3.8-jupyter
source ~/venv-3.8-jupyter/bin/activate

1. I think it should be python3.8 not python 3.8
2. I think it would be better to be source venv-3.8-jupyter/bin/activate without the ~/, seeing as most people probably won't set up the virtualenv in ~/

I started with code to draw chart symbols down in the bottom of the chart file:

But they don't currently work and I haven't debugged why. If anyone else wants to play with it before I get to it, go right ahead!

Currently the charting software expects a symbol (see #10) , but for colourwork knitting we'd probably want to accept a colour value in the legend and have it fill the square with that colour.

Here's an example of a fairly typical colourwork motif as part of a pattern:

https://www.dummies.com/crafts/knitting/knitting-projects/how-to-knit-a-headband-with-a-fair-isle-snowflake-pattern/

two-colour patterns are often represented as dark grey and white for various reasons (good contrast for most types of vision, less distraction if you're knitting in an alternate colour, cheaper to print) but we'd likely want to accept any arbitrary colour so folks doing interactive patterns could change the legend to suit their preferences in the moment.

The main() function isn't working properly.

Attempt 1: in the CLI: pyknit 'k2 p4':

pyKnit 0.0.3
Traceback (most recent call last):
  File "/Users/bhampson/code/learn/pycon-us-2021/pyknit/venv-3.8-jupyter/bin/pyknit", line 33, in <module>
    sys.exit(load_entry_point('pyknit', 'console_scripts', 'pyknit')())
  File "/Users/bhampson/code/learn/pycon-us-2021/pyknit/pyknit/pyknit/pyknit.py", line 213, in main
    print(pyknit.parse_written(args.instruction_row, legend))
NameError: name 'pyknit' is not defined

Attempt 2: Running using the venv Python interpreter: /Users/bhampson/code/learn/pycon-us-2021/pyknit/venv-3.8-jupyter/bin/python /Users/bhampson/code/learn/pycon-us-2021/pyknit/pyknit/pyknit/pyknit.py:

Traceback (most recent call last):
  File "/Users/bhampson/code/learn/pycon-us-2021/pyknit/pyknit/pyknit/pyknit.py", line 13, in <module>
    from pyknit import GaugeSwatch, Chart
  File "/Users/bhampson/code/learn/pycon-us-2021/pyknit/pyknit/pyknit/pyknit.py", line 13, in <module>
    from pyknit import GaugeSwatch, Chart
ImportError: cannot import name 'GaugeSwatch' from partially initialized module 'pyknit' (most likely due to a circular import) (/Users/bhampson/code/learn/pycon-us-2021/pyknit/pyknit/pyknit/pyknit.py)

Related error:
https://github.com/terriko/pyknit/blame/main/pyknit/pyknit.py#L200
parse_written is not imported.

We should add a brief explainer about pip install -e for folk who want to run pyKnit in "developer mode" and have edits show up live. https://pip.pypa.io/en/stable/cli/pip_install/#install-editable

There isn't really a separate developer doc, but it could probably get a section in README.md for now.

The parser for written instructions is very basic and can't handle repeats. I'd like to make sure it can at least handle parsing the output of our math functions (e.g. sleeve_decrease and increase_evenly), and maybe venture into other common ways of written repeats later.

I forgot to run a spell check on https://github.com/terriko/pyknit/blob/main/documentation/SleeveDecreases.md and almost certainly left a few typos in. If someone wants an easy first contribution, run a spell check on that file and fix it up!

It would be nice to have some creative commons licensed artwork for explaining certain types of measurement in our documentation and in interactive patterns. Here's an example of a non-creative-commons (but free) pattern helper blog post that includes extensive diagrams:

https://blog.tincanknits.com/2013/10/25/lets-knit-a-sweater/

The idea here is to have some artwork as part of pyknit that people could re-use without copyright concerns, so finding something free on the internet that has an explicit permissive license would be ok, but including diagrams from free (but not permissively licensed) patterns would not. It's probably easiest to draw some new stuff since knitting diagrams are not typically creative commons licensed.

Some diagrams we could use right now:

• How to measure gauge.
• sweater sleeve measurements

I am delighted to find this open-source project! Python is not a language I often code in, but I will attempt to provide support for this issue myself. Any help on it or if someone can easily add this feature - that would be greatly appreciated.

I enjoy the charting feature as demonstrated by the Cabled Cowl demo and I noticed thanks to another issue listed that the chart symbols were pulled from this site by the Craft Yarn Council - Site Link.

That site does show the Japanese symbol alongside an 'other' set, but this project currently supports only the 'other' set of symbols. I'd love the stitch legend import to support both types of symbols, perhaps creating a toggle on which ones to use. I was thinking that the 'other' symbols could remain the default, and a command could be used such as
stitch legend = setStitchLegend(Japanese)
(Forgive my Java accent :) )

An alternative method would be to create a duplicate that could be imported instead of stitch_legend, called stitch_legend_japanese. I'm not sure which would be an easier or cleaner implementation yet, as I haven't dived into the code.

I am very fond of Japanese Knitting Charts and use them almost exclusively. I would heavily use pyknit to convert verbal instructions I found into a Japanese chart given the opportunity! I think this software has amazing potential for a code savvy knitter, and I'm looking foward to using it more.

Currently, the pyknit error messages are all print statements that go to standard io. Before we get too entrenched in our ways, it might be nice to change them to "proper" error messages. (I don't really think anyone cares too much at this stage, but I'd like to model best practices)

Likely options:

1. Use the logging facility for errors: https://docs.python.org/3/library/logging.html
2. Raise exceptions and handle them per https://docs.python.org/3/tutorial/errors.html

Other projects i'm on use a combo of both. However, part of the fun of having a tiny project is being able to try new things, so if there's any brilliant new error handling system we might want to check out, this issue is a good place to mention it.

If you make a gauge swatch with measurements set to 0, it's going to give you bad math. We should probably handle that with an appropriate error when you initially try to set something to 0 so you don't get surprised later.

We might also want to make some way for a user to specify "I never measured this part of my gauge" if they want to do measurement conversions for only rows or only stitches.

I haven't really done much reading yet, but pyscript sounds fun and it would be cool if we could get pyknit running in the brower without jupyter for folk who don't have it installed.

Hello, I'm a rookie knitter. I can barely finish a knitted headband, but I've just got this idea from researching how long it takes to knit a pair of socks:

Is there a way to write a script that calculates the number of stitches a project requires (X)? Then multiply X by the amount of time it takes to do that one stitch (N seconds)? The final result is X * N, the approximate time it takes to finish the project?

Of course that doesn't take into account the time spent on consulting the pattern, learning a new technique, ripping mistakes etc.

This is one of the shawl shapes mentioned in #11, but I'm describing it here in more detail so it's a more bite-sized issue.

A pi shawl is a circular shape with regular increases as the radius of the shawl grows:

https://www.craftsy.com/post/pi-shawl-patterns/

But pi shawls, while still worked from the center out, only require a few shaping rows in the entire project. Basically, every time you double your distance from the last increase round worked, you work another increase round. These infrequent increase rounds make pi shawls a great option for lace knitting.

It would be nice to have a function that, given a gauge swatch, could tell you how many rows to work between increase rows to get the desired flat circle, printed as a pattern or as a set of numbers, and maybe also have it calculate how many rounds you'd need to reach a desired size (given the gauge).

Similarly, a half-pi shawl is the same idea but only half the circle is worked. The math would be the same for how many rows to work but the instructions would be different. You'd probably want to make half-pi an option on the full-pi function.

The chart function has a fairly small initial stitch dictionary, focusing mostly on stuff we could easily do with a default font. It would be great to have a larger default library for folk to use.

The craft yarn council has a list of knit chart symbols that would be a good initial library. We'd need to find a way to draw all those symbols. I think what we'd want is little SVGs for each symbol so they could be resized as needed, but I'm open to other suggestions of things that can be drawn from Python. (Knitting fonts do exist, but I haven't seen something with a compatible license, and we'd want something we could distribute with this GPL2.0+ project)

Right now, decrease_evenly is just a stub without any code:

https://github.com/terriko/pyknit/blob/main/pyknit/pyknit.py#L62

it's probably going to be somewhat similar to the sleeve decrease function, with the ability to add padding at the beginning/end of a row.

I didn't put much in the way of error handling into the math functions, and we should probably fix that so people get a warning if they enter something that doesn't make sense.

Examples:

• The way increasing stitches with m1 (make 1) usually works, you can only add as many stitches as you had to start. So if increase_number > starting_count in the increase_evenly() function the instructions don't actually make sense. We should throw an error instead
• Entering 0s isn't going to make sense in a bunch of these either
• Negative numbers either. We could maybe import some sort of unsigned type, but for now I think just an error would be fine.

We should add some basic unittests in the tests directory to make sure the calculations make sense.

Generator functions for various component shapes. Similar to the sleeve decrease function we already have, you'd want these to take starting/ending stitch counts so they could be customized using actual gauge as needed. Eventually, we'd want to be able to apply pattern fill to all of these.

Some ideas:

Common components (similar to the sweater sleeve decrease function we already have):

• sock toes
• sock heels
• raglan sweater yoke
• round sweater yoke (top down/bottom up?)
• pockets?
• hat - beanie style
• hat - brimmed style
• hat - slouchy style
• hat - other styles?

Shawl shapes:

• square
• rectangle
• biased rectangle
• triangle
• elongated triangle
• asymmetrical triangle(s)
• pi shawl
• half pi shawl
• crescent

More component ideas welcome in the comments, and links describing how these shapes are made would also be helpful!

I'm going to file some shapes individually as I find them so they're easier bugs to work on at one go.

It would be nice to have an example notebook that people could download to run pyknit and see how it works.