FABulous API

[mole99]

It would be great if FABulous could be used directly from a Python script to programmatically generate fabrics in different sizes/configurations. I know there is the option to load a tcl script, but I think this would allow for more functionality.

It seems like the framework is actually fairly well separated from the CLI. Still, there are some changes I would suggest to make the usage from a Python context easier/smoother.

1. Separate the CLI and the FABulous class into two files

2. Pass fabric description as a Python variable

   The fabric description should be passed to FABulous as a Python variable, e.g a dictionary. The CLI can still read fabric.csv, but has to convert it first before passing it on to FABulous. This allows the generation of variable sized fabrics without having to write a fabric.csv each time.

   I think Separate Fabric and Tile description #149 would help here.

3. Move some functions from CLI to FABulous

   For example do_gen_tile/do_gen_all_tile is a rather large function that should be moved to FABulous. This function is used in the CLI and is also be needed when building the fabric programmatically, thus preventing code duplication

4. Create a tile manager class and separate it from FABulous

   Since tiles are mostly independent of the fabric and can be used by multiple fabrics, I think it might make sense to move the tile management to a separate class.

   Imagine you want like to programmatically generate differently sized fabrics that uses the same tiles. Currently, you would create three times a FABulous object pointing to the same tiles. The first FABulous object generates the tiles and writes the fabric. The other two FABulous objects only write the fabric without regenerating the tiles.

   With this approach, one tile manager would be created that generates the tiles. This tile manager is passed on to the three FABulous objects, generating three differently sized fabrics.

5. Document the API usage

   Provide an example of how to use the API and generate a fabric programmatically.

[mole99]

I am currently working on a project that would benefit of the programmatic generation of fabrics. Therefore, I would like to work on these points. But first I wanted to ask for your feedback :)

[KelvinChung2000]

1. I just discussed with someone today, and I agree we should further separate the CLI and the FABulous class into two files.
2. The user can create a Fabric object directly, but we have not yet provided an API for generating the thing. You can add an API to allow this to happen, but you will need to consider how to capture all the information in the CSV and a reliable way for the user to provide all the information in the CSV. The CSV files also have links to some .list and RTL files. Capturing all this might be challenging and require a lot of time.
3. Creating an API for generating tiles makes sense so the CLI can be cleaner and enable more features.
4. Tile generator is implicitly implemented. The generation of a tile starts with generating a tile object and then creating a deep copy of the tile, which is appended to the tile list in the fabric object. You can access individual tile type general information with the tileDic attribute.
5. A programmatic way of generating a fabric is not the primary goal but more of a by-product of the re-factoring (have a look pre FABulous refactor #50 ); however, this is indeed something I can see people will want to do with FABulous. Hence, you see the separation between the CLI and FABulous itself. There is no example because you are the first person to do it. I am happy to help with your problems while you develop the feature.

Since most of the things you want to do are related to generation, I recommend you look at the fabric.py and the file_parser.py, which contains all the logic for building the fabric object. The rest of the framework should work once a correct fabric object is created.

[mole99]

Great to hear that an API for FABulous is something that is wanted!

Thanks for all the feedback, I'll try to get started on these points. Once I have some results, I'll open a PR so everyone can view and comment on it.

[mole99]

Just for your information, I have currently paused work on this, but I will soon pick it up again in a month or two as I'm going to need this for my masters thesis ✌️