Python module and package naming

[wizofe]

Currently the Python SDK isn't packaged in a way that allows it to be imported as a module. I am very happy to help with this but there are a few issues, most important (at the moment) the name!

As I know already, @malminhas was excited to see a library with an import kano or from kano import motionsensorkit) etc. I think that's exciting and it would make sense from a user perspective.

To achieve this, it would mean that the base folder name communitysdk should be renamed to kano. I don't believe that would interefere in any way with the KANO OS (in my knowledge the only place where a similar Python KANO library exists) as:

• The target group is completely different. No user of the KANO OS, would experiment with our libraries as they are very closed and specific
• The current libraries don't support Python 3 (Only <= Python 2.7)

If people agree on that, I can offer the PR fixing the issue, by creating a Python Package following the Packaging Guide (which can easily be converted in a future Native Debian Package that would be able to be included in the main Debian OS as well, and so to reach literally everybody who owns a Debian (and Debian-based including Ubuntu, Kali, PureOS, Raspbian).

What people think? @murilopolese @malminhas @russormes

[murilopolese]

I'm happy to rename the folder if it's a common will but I'd like to point a few things that I considered before picking the name communitysdk:

• I'd like to make very clear the difference: This is not the :1st_place_medal: official Kano's SDK, this is Kano's Community SDK which has goals and a roadmap that might differ with other present and future Kano SDKs. It's official enough to excite people to contribute but informal enough to give contributors freedom to submit code that is not so professional and tight. We can make this THE Kano SDK but I believe it's a bit early to such compromise :).
• I hope one day there will be a Kano SDK that will have better performance and wider application than the Community SDK is now. In that sense I see more the Community SDK living inside a kano package than being the kano package. I imagine a future where from kano.community import MotionSensorKit and from kano import MotionSensorKit will coexist.
• Would be cool if we could call all the Community SDKs by the same name, not a big deal if it's not possible but that is why I picked a name I don't think anyone else will claim, without special characters and that could sit after a kano namespace like on a possible npm package called @kano/communitysdk.
• Installing via pip is a real nice to have but I believe the excellent experience for a beginner/my hacky-maker™ would be downloading the zip with the source, opening an example on Mu Editor and clicking run.

A quick tip/solution would be simply renaming it on your local version! All the relevant imports are relative and as you can download it without installing via pip nothing will stopping you from renaming the folder to kano and using exactly like you suggested.

[anzellai]

As an end user, I’d suggest we don’t create different branches to cater different programming languages, but to create a folder structure that shows clearly which programming lanaguages we support. This also reflect how usually open source project manages themselves.

If this is a repo for unofficial packages, we may consider having a structure like:

GitHub / KanoComputing / Community / KanoSDK / [node | python ]

In this case, we can put individual package publishing files under sub folder, and still give more advanced user to git clone the project. Also to avoid the popular “from kano.kano import kano” that kind of deep path.

One caveat is that when we tag the release, we need to be careful on syncing the api and docs, and bring all subfolder up to the same tag.

[wizofe]

This issue is not about branching.

@anzellai feel free to open another issue for that; Out of Subject.

[malminhas]

My thoughts on this. We should rebase to ensure that a user is able to access Kano functionality in a way that is logical and consistent and serves to demystify itself. In a Python context I am clear this means I should be able to access Kano functionality via a kano module and do the following from a Python 2 OR Python 3 REPL so I see what is available for me to access and play with without recourse to documentation: import kano dir(kano) in the same way I can do this in Mu today to 'dial up' what I can do with Turtle: import turtle dir(turtle) Ref. pip installation, that is a goal for the Community SDK so I agree with @wizofe that we need to ensure we get the naming right here otherwise I suggest many users will end up doing this: import communitysdk as kano Unless we are talking about having kano module built into the corresponding Kano OS release, users will have to install and my view is that anyone wanting to install the kano Python module is almost certainly going to have used pip at some point to reliably install other Python modules and their dependencies. It would be reasonable for them to assume we make it easy for them to find our module in PyPI thus: $ pip search kano kano (0.0.1) - Kano Community SDK

[murilopolese]

We should rebase to ensure that a user is able to access Kano functionality in a way that is logical and consistent and serves to demystify itself. In a Python context I am clear this means I should be able to access Kano functionality via a kano module

I agree with what you say but I have a hard time understanding why exactly naming this module kano instead of communitysdk (or anything else) will make the SDK more logical, consistent and able to demistify itself.

In fact I personally have already experienced in workshops, fairs and friends confused about what is Kano? Is the tiny board? Is the keyboard? Is the OS? Is the character (judoka)? Is the website? Kano is many things and the way we currently do is to prefix Kano to the things we make: Kano Computer Kit, Kano OS, Kano World, Kano Code App, Kano.me, Harry Potter Kano Coding Kit, Kano Pixel Kit, Kano Motion Sensor... This way the logic and consistent way to do it would call it Kano Community SDK, no?

But we can call it something and import it in a different way, for sure! But knowing that so much code is already floating around losely labeled kano (there is even a kano2 shared library that is only used by one app) doesn't make me very comfident this is a "future proof" name. Am I too conservatite to think of kano as a namespace instead of this specific project?

from a Python 2 OR Python 3 REPL

Python 2 support in the future, right? As I believe the main experience we are going to push soon (next months starting now!) for this SDK is through Mu Editor, we should perhaps assume we will be using the Jupyter console provided by Mu (Python 3 exclusive).

import kano dir(kano)

I guess that is confusing, what do you expect to see as result of dir(kano)? I would think it would print something like this:

In [1]: dir(kano)
Out[1]: 
['os', # cool tools and things you can do on the OS
 'world', # authenticate, fetch and submit to Kano World 
 'hardware', # integrate Kano hardware in your "production" software
 'communitysdk', # sugar coated api for you to interact with Kano hardware
]

But again, that is me thinking of kano as a namespace rather than this specific project (which lives inside the EDU Avanced Projects scope).

Ref. pip installation, that is a goal for the Community SDK

Well, is it? I believe (and translated this belief in the goals and roadmap) the Community SDK is one of the deliverables of the EDU Advanced Projects. In that context having to install a package from pip is nice and you should definitely be able to do it but once you know what is a dependency and that you can install them through a package manager.

I might be doing it differently than the usual, but I believe that this step comes a bit later on the process of learning to program in Python (or in any other language). Before that I usually introduce the paradigm of having files that interact with other files and are executed by an interpreter/IDE. Imagine starting a class saying "OK! Let's install the zorg with blorg so we can do xorg". Zorg being package, blorg being pip and xorg being programing in Python. On the other hand saying: "OK! Download this 'zip' file, extract and open it with Mu. Now press Run!". Those are terms our target audience will probably be more comfortable with.

Also on our target scenarios (again, EDU Advanced Projects) like a workshop on a library, school or children-safe environment, it's much easier to convince the "IT people" to install one trusted software they will be using for many purposes (Mu Editor) than saying we need to install a package manager that will allow us to install a bunch of other things and we might need to have adminstrator access to install a specific package that access serial. You have ran Code Clubs and are aware this is a problem that Jupyter Hub tries actively to solve.

Comparing the requirements, this and this instructions and which one seems to be more friendly? :)

import communitysdk as kano

To be honest, I see that as one of the greatest oportunities to talk about as in the import! Don't like the name of a package? You can rename it to fit your naming style ;P

having kano module built into the corresponding Kano OS release

Isn't that the ultimate dream? You get your Kano Computer Kit, get a nice onboarding that teaches you how to use the terminal and eventually put yourself in front of a REPL where you can just type import kano; dir(kano) and eventually things like lightRing.setColor(red)?

After writing this and consulting Taylor, I'm pretty confident this project and package should not be renamed to kano. It's tempting because, well, we work a company with a real nice name! We should eventually have a package called kano but for an idea that started as something that wouldn't even be branded as oficial Kano content, renaming it to kano is a bit of a stretch to do right now. We can still use the powers of Python to rename this SDK to kano locally but Taylor reminded that perhaps we should take this discussion again once we have tested, succeeded and with a team to work on it. Shall we?

[netmanchris]

Getting up to speed, but the main issue I see with "communitysdk" is that there's no obvious relation to Kano in the package title. Perhaps a compromise would be pykanocsdk ( Python Kano Community SDK ). Best and worst part of python is all the packages that are out there. Finding what you're looking for is hard. Making sure that it's searchable with a fairly obvious label is something that's important. I'd also be happy to work on this.

I would also suggest potentially putting some placeholder projects like kano or pykano or something like that in pip to guard the name against someone else taking the package name.

[wizofe]

@netmanchris thank you Chris for the input. Unfortunately it has not been a unified open source approach right now but a few of us want to change that.

If you are using (or you plan) to use the wand feel free to have a look at this as well: https://github.com/wizofe/bluewand-python

[netmanchris]

@wizofe Very Cool! I was actually looking for exactly the wand drivers. Count me in for someone willing to do some contributions if we can get this off the ground. Also forked the bluewand-python library and will start hacking away on that. Really appreciate it. Not sure I would have found it otherwise. :)

[murilopolese]

Yeah, @netmanchris ! Thanks big time for the input!

I'm all for an unified open source lib, naming pattern and even API for all Kano devices (as much as possible)!

I believe the naming choice, positioning and development of Community SDK (all my responsibility) were a bit unfortunate in a few aspects, therefore my resistance in patching the name. Perhaps there should be a movement of destruction or reconstruction of this repository ahhaha! No hard feelings if this is the best way to move forward and please our users :)

@netmanchris In that sense feel the name pykanocsdk it's not necessarily the most appealing and efficient name if we take a moment to think about the initial target audience for this SDK: Teachers and young students just coming out of block code (Community SDK is a project under the EDU Advanced Projects umbrella). I saw many times in classroom and workshops the struggle for typing basic for loops and simple variable names. I'd rather put names that are written as they are spoken or easy/obvious to remember (Carrie Anne, from Raspberry Pi Foundation talks a bit about this here: https://youtu.be/_gU7sfTrz4c?t=1341).

It turns out that some things that are good for the targeted users are also nice to a more general audience and the main initial goal for the Community SDK got a bit blurred. As it was designed this shouldn't be a pip package but something you can just download and run (mostly on Mu Editor). I did the best job I could but of course there is tons of room for improvement. I would just like to keep the changes aligned to the initial idea as much as possible until we all decide the initial idea is no longer interesting :)

I hope that clarifies a bit why this issue is a kind of stuck :D

[netmanchris]

@murilopolese This makes a lot of sense. My suggestion of the name was for something as simple as making it easy to identify that this is a community effort rather than something provided directly by Kano with some more polish. :)

As a more technical consumer of the Kano hardware line, what I'm looking for is a python SDK that's installable through pip that I can leverage to quickly get up and running and use the Kano hw-kits in new and creative ways. Linking them with other platforms I'm working on as a way to bridge the physical and the API driven world.

Hypothesis: Considering there's a least a couple of us ( @wizofe and myself ) that seem to have a similar requirement in mind. Does it make sense to start a new repo for the the PIP packaged version of this? It looks like all of the initial requirements are already done in the community SDK version so it should be quite quick to get moving on this. (This should definitely live under the Kano org I believe. )

Obvious risk is that the community SDK and the "real" python sdk would drift from each other in functionality and API. Not something that I think would be good for any of us.

Just thinking out loud. :)

[murilopolese]

@netmanchris Yes! And I forgot to mention your idea to create placeholder projects to keep the names is fantastic! I'll definitely pass this idea forward to whoever has the power to do so! Excellent tip!!! 🥇Ping @malminhas!

Also not having "Kano" on the package name might be an SEO problem but I was actually counting on other things like this to get this job done hehehe!

About your hypothesis, the intended target audience is not really giving a lot of feedback yet. Teachers are hard workers and usually operate on 110% of their capacity so it's natural it will take some time before we get some feedback. I'm officially waiting until December before making hard decision.

After that, it's possible that there are more people complaining about the name of the module than noticing the bugs, memory leaks and inconsistencies in the API. If that is the case, it's crystal clear what to do: Rename it or even repurpose it from what we learned. Don't hesitate to point other things you would like to see on the SDK, your opinion as a community member it is already weighting!

Meanwhile, I believe that by adding a setup.py and running a python setup.py you could install it globally just like pip would do on your machine and eventually do the integrations you want! @wizofe can definitely help you more than me on this hehe! If you do it, please share it with us so we can add to the wiki!

May I ask, out of curiosity what are the projects you are planning to use the SDK with?

[wizofe]

@netmanchris that was my worry as well in the beginning and as I am also part of KANO, it initially was opened as an internal discussion/decision :) @murilopolese had a different agenda for the project and that's pretty understandable as he's targetting a different audience. Also, the community-SDK is the way to re-use, extend and make even more interesting the Pixel Kit (at the moment).

In an open source world, I expect that it's nice to see collaboration and forks; feel free to go forward with that, as my dream would be in future to be able to do a:

from kano import pixelkit
from kano import wand
from kano import (new product)

:)

Rgrds, i.

[netmanchris]

@wizofe

We share a dream. :)

@murilopolese Of course you can ask about projects! To be honest I've got a few different things in mind. From using the Kano kits as props during speaking engagements, to a couple of smart home related projects where I have headless sensors in locations without any way to view the data that does't involved me having to pick up a phone/tablet and browse to webpage. The Pixel kit would seem an awesome way to bridge the gap between the physical and virtual world.

I'm also running home-assistant as one of my platforms and I'd love to be able to use the wand and/or motion sensor to be able to trigger specific functions (automations) . Imagine "wave magic wand to turn the lights on/off". Of course there's a lot more details to work out here, but those are some of the simple versions.

For me, having a library that's on pip and importable is a pre-req to making some of this happen and transportable between platforms. I can definitely work the work here, write the setup.py file and push it to pip myself, but it really seems like this is something that should live in the Kano org's control. I would be a happy contributor. :)

Thoughts?

[murilopolese]

That is a dream indeed!

I'm very excited about your projects and puzzled about the blocking points you see. I hope my comments don't deviate the main discussion about the name but make a point on why the SDK, as it is or with very minimal changes, already does all you want including pip installs.

Your projects sounds like awesome additions to the examples and Kano's blog content straight away so if you manage to implement any of them, please let us know!!!

That been said, I have a few things to point out:

• In any situation involving the Community SDK you will need a more powerful computing device (running Python, obviously) to constantly stream frames to the PK. This is a firmware limitation.
• Might be worth for you to try displaying "fake" data on the PK before you integrate with the sensors. From personal experience it might be trickier then you imagine to plot meaningful information on a 16x8 RGB matrix. Even if you choose to fork and develop a "parallel SDK", this will give you a lot of things to think about before thinking about distributing across platforms :) Specially because I haven't included a xy drawing method and, in my humble opinion, this might be a higher priority in terms of contribution than changing the name.
• Unless you do something very smart, you will have your Pixel Kit on all the time and it will probably give you no more than an hour before the battery dies. Therefore you will whave to attach it to the computing device that has access to the sensor data. The Python SDK is lagging behind the NodeJS in terms of features and one of them is WebSocket connection which is also, in my humble opinion, a higher priority.
• I just found out that pip, as any respectable package manager, has VCS support. With the addition of the setup.py (pull requests welcome!) it would be possible to install it straight from git. Once installed, you can always import communitysdk as somethingelse or perhaps fork the project just to rename it, that is a valid and expected behaviour ;)

As you see, there is a lot of room for contribution and you are very to take any path from here: fork to work on naming/packaging, feature pair the Python SDK with the Nodejs SDK, work on roadmap features or fix the nasty bugs I can't figure out how to solve!

[wizofe]

@netmanchris

Without giving out more details or wanting to create any dispute here (but feel free to email me and discuss further if you're interested) I believe that the best way here is to 'fork and play'.

I'm happy to start that structure (outside of my KANO affiliation and purely in my spare time), as this is the way I grew up with: open source, it's community and power. I definitely don't want to do all the work and support myself) but I'm going to set the milestone or being able to create a multi product pypi package, that anyone can import.

@murilopolese has a very specific agenda towards the education sector and a very specific niche part that he made a big effort to open source and bring out to the world. Let's grow this further/according to expected needs.

[netmanchris]

@wizofe If you're willing to start the structure, I'm more than happy to make some contributions. It does sound like @murilopolese goals for this repo don't currently align with the structure required for putting together a combine package. If you want to create the project and place a link here so I can find it, I'll be happy to extend.

[murilopolese]

It does sound like @murilopolese goals for this repo don't currently align with the structure required for putting together a combine package.

If by required structured to put together a combine package you mean renaming the project and SDK (thus breaking the API for the existing people with less then a month of launching of project) then yes, this is not the goal.

If you mean refactor code in a less "revolutionary" way to add new features, devices and contribute for the list of things on the roadmap (including making it able to install via pip) then I think you read me wrong: I do want to make a combined package!

Both ways I strongly recommend you to not feel blocked: Fork or start your own version of this project! And pretty please post it here so I can read and perhaps incorporate in the appropriate time :D I'm keen to learn new approaches and design patterns as much as I'm willing to keep this project aligned with it's guidelines and audience needs.

I hope a simple thing like the name of a project won't push you away but if it does, leave a breadcrumb so we can cross paths in a near future!