Suggestions/Feedback

[gbaman]

After taking a look over the project, I can make a few suggestions @TreasonMay .

Project structure

• Laying out the project as a library

  • To end up a Python library, there are a few adjustments I would suggest making to the repository. Generally you have project_name/project_name/init.py along with all your other project files. This allows you to put setup files etc within the root directory, then the library itself is only in the sub folder. For example, see pyjokes. It has a lot else in there, but it has the rough idea. This is a great guide as well.

• PEP8 support

  • This is definitely one of my big ones, but it isn't the end of the world. To help developers using your library, I would suggest switching over to PEP8 formatting. So that would mean

  awesome_variable = 1
  def awesome_function(awesome_thing):
     pass
  class AmazingClass():
     pass
  - In addition to the above, all file names should also be lower case.

• Add a .gitignore file

  • This avoids you by mistake uploading your virtual environment folder (I would suggest removing this) along with uploading your .idea folder. This is a pretty good example of one you can use right away for Pycharm, that also covers Python itself.

• Splitting out into multiple files

  • As you grow the API, you may wish to flesh it out into multiple files. This makes it all a bit easier to manage. For example, you might want an auth.py file, tasks.py etc etc.

• Examples

  • Examples generally live in a folder of their own, with the file titled what they actually do. See for example this repository.

• Add a requirements.txt file
  - This is pretty important given you are using requests, which isn't in the standard library

Documentation

• Right now there isn't any. Take a look at code based documentation. Perhaps something like pdoc, which is pretty nice. Pycharm I am pretty sure supports even writing most of it...

Code specifics

• You might want to look at the Python typing library. It is very easy to add type hinting to your library and it allows IDEs like Pycharm to auto predict types being passed back or into functions etc. It makes them a lot easier to work with, especially when using custom classes.
• Classes for items being returned might be useful? For example, a Task class?
• I am a much bigger fan of fstrings than + syntax, given auto type casting. This one is up to you.
• I don't know if you have tried out Python @Property, but they can be a very clean way to return values from a class, without requiring them to be treated as functions. It is simply cleaner when you don't have a value to pass in. For example

  class Thing():
     _name = "bob"
  
     @property
     def name(self):
        return self._name.capitalize() 
  a = Thing()
  print(a.name)

Hopefully that is enough to get your started for now.

[TreasonMay]

@gbaman This is the API thus far. I am yet to arrange it into the style of a library, but I have split it up into multiple files, added docstrings, started using objects and classes etc.

I have decided to go with Google style docstrings as they seem more intuitive.
I have looked into the typing library, however I'm not sure if it is sensible to implement it now since the docstrings do most of the explanation for now, however as the library grows I will add them.

I still need to finish the ActiveTaskInterface (a class similar to TaskInterface, but it will store tasks and poll Firefly for any updates, and will accommodate listeners and include more details about tasks), along with a few minor changes. Then I think I am ready to make this public.