Improve poetry usage documentation

[xywang84]

Greatly appreciate the work done in this project, I had recently gotten a build of this to work on May 2nd, but it seems like the installation process has changed dramatically in this short time. Haivng some problems with the new flow, and would appreciate some help in resolving if possible.

Running on a Raspberry Pi Model 3B+ on Buster. Python version is 3.7. After running the newly updated install process using:

poetry install
pre-commit install

The installation appears to be successful with the following output:

pi@raspberrypi2:~/www/python/python-kasa $ sudo poetry install
Creating virtualenv python-kasa-BwJufRoA-py3.7 in /root/.cache/pypoetry/virtualenvs
Installing dependencies from lock file

Package operations: 40 installs, 0 updates, 0 removals

• Installing zipp (3.1.0)
• Installing importlib-metadata (1.6.0)
• Installing pyparsing (2.4.7)
• Installing six (1.14.0)
• Installing appdirs (1.4.4)
• Installing async-generator (1.10)
• Installing attrs (19.3.0)
• Installing certifi (2020.4.5.1)
• Installing chardet (3.0.4)
• Installing distlib (0.3.0)
• Installing filelock (3.0.12)
• Installing idna (2.9)
• Installing more-itertools (8.3.0)
• Installing packaging (20.3)
• Installing pluggy (0.13.1)
• Installing py (1.8.1)
• Installing sniffio (1.1.0)
• Installing urllib3 (1.25.9)
• Installing wcwidth (0.1.9)
• Installing anyio (1.3.0)
• Installing cfgv (3.1.0)
• Installing coverage (5.1)
• Installing identify (1.4.15)
• Installing nodeenv (1.3.5)
• Installing pytest (5.4.2)
• Installing pyyaml (5.3.1)
• Installing requests (2.23.0)
• Installing termcolor (1.1.0)
• Installing toml (0.10.1)
• Installing virtualenv (20.0.20)
• Installing asyncclick (7.0.9)
• Installing codecov (2.0.22)
• Installing pre-commit (2.4.0)
• Installing pytest-asyncio (0.11.0)
• Installing pytest-azurepipelines (0.8.0)
• Installing pytest-cov (2.8.1)
• Installing pytest-mock (3.1.0)
• Installing pytest-sugar (0.9.3)
• Installing tox (3.15.0)
• Installing voluptuous (0.11.7)
• Installing python-kasa (0.4.0.dev0)

pi@raspberrypi2:~/www/python/python-kasa $ sudo pre-commit install
pre-commit installed at .git/hooks/pre-commit

However after this is done, there is no kasa module in my python3.7 and the previously working "kasa" CLI program is not found on the path.

With the previous setup.py based flow, the kasa libraries were installed at a location in the $PATH but this is no longer the case.

Question is where is the kasa.py CLI program expected to be? And why is the kasa module not linking to my python environment?

I originally thought running this as root with sudo would possibly work, but no luck there either.

Thanks!

[xywang84]

Ok digging into this a little further, it seems like I totally misunderstood what poetry is about (this project is the first time I've ever heard of it, being not well versed at all in the python development world). It seems like it installs everything in:

/home/pi/.cache/pypoetry/virtualenvs/python-kasa-BwJufRoA-py3.7

and creates a virtual environment. So i can seem to be able to run the kasa program in the bin/ directory there. I can load the kasa module if I run python from the directory i cloned git into and ran the poetry install process in. However, running python in any other directory the kasa module is not found. I assume this is by design.

Given this as the case, as someone who isn't well versed in how things should be done, what is the proper way to use the kasa module outside of the directory with the virtual environment?

Thanks.

[xywang84]

Ok looks like you also have to append $GIT_DIR/python-kasa into your sys.path as well.

I guess the previous install flow made all of this automatic (or maybe it was because I was running those within a miniconda environment in MAC/Linux Subsystem from Windows) but in RPI it seems like you have to add the links yourself.

So based on my experience, kasa executable is in ~/.cache/pypoetry/python-kasa-....-py3.7/bin
And to use python modules, need to add $GIRDIR/python-kasa to your sys.path.

Perhaps it would be helpful to put this in the README to help out more amateur people like me? But there is no bug in the code or install process.

Xiao

[rytilahti]

Hi and thanks for the report (and testing)!

First things first, it's practically never a good idea to use sudo to install python packages, instead of having virtual environments ready to use. Likewise, it's better to avoid modifying sys.path manually.

Anyway, this is actually one of the things that makes poetry a bit annoying from end user perspective. The idea behind having separate virtual environments is to make sure the installation is always in a workable environment, but this does not play so well with entrypoint scripts (as you noted). One potential way, to my understanding, could be to use https://github.com/pipxproject/pipx to manage the installs (which in turn handles environment separation while still storing the entrypoint scripts, like kasa, in a centralized place).

As soon as we have a release out, it will be simply a fact of pip installing the package wherever wanted. At the moment the same behavior can be achieved by building a wheel and installing it with pip as usual:

$ poetry build
Building python-kasa (0.4.0.dev0)
 - Building sdist
 - Built python-kasa-0.4.0.dev0.tar.gz

 - Building wheel
 - Built python_kasa-0.4.0.dev0-py3-none-any.whl

$ pip install dist/python_kasa-0.4.0.dev0-py3-none-any.whl 

For development setup, you can use virtualenvs.create setting for poetry (https://python-poetry.org/docs/configuration/#virtualenvscreate-boolean) for the specific project by calling:
$ poetry config virtualenvs.create false --local
or globally:
$ poetry config virtualenvs.create false

which allows to install the package with poetry installinto your current environment.

edit: actually, if you have already activated virtual environment, it will be used automatically, so there is no need to change the poetry configuration.

What is your end goal? Are you thinking about changing the code, or just using it? If the latter, the build&install approach is the way to go..

This needs definitely to be documented, so I'm going to reopen this. I'm unsure what is best approach to document, though...

[xywang84]

Hi sorry for the late response to this. Thanks for the information! My use of this was solely as an end user, not sure I'd have too much to contribute as a dev, so my goal was to simply build and install. I didn't even know anything about building a wheel and installing it, and it seems like that last piece you put up would be really helpful to have in the README. Thanks for the responsiveness!

[theyosh]

Or, is it possible that @rytilahti put the pip package to https://pypi.org/ ? That would make the installation super easy for end users. And make me very happy :D

[rytilahti]

Yes, the plan is obviously to put it in pypi :-)

I'm just waiting for the merge of two PRs (#63, #65) before doing that. The plan I had in my mind is to make a dev0 release on pypi to gather some feedback, and iterate those test releases until we are confident that everything is working smoothly.

[gerardpc]

Dear all,

I have seen that there is some recent discussion regarding the installation process. I am not in a hurry, so if you are you going to upload the package to pypi I can definitely wait. I just wanted to say that it might be a good idea to include a little bit more information on how to setup everything the first time in the general Readme file. I was a bit confused until I saw this thread...

Keep up the good work and thanks!

[theyosh]

Same here. For now, I can work with the explanation here to make the local pip package. So there is no hurry from my side.

[rytilahti]

Yes, the README needs to be made more approachable and it's on my TODO, but until then, I created a pre-release (0.4.0.dev0) which is now available on pypi: https://pypi.org/project/python-kasa/ . So passing --pre to pip will allow installation until a proper release is made:

virtualenv venv
source venv/activate
pip install --pre python-kasa

[pidg]

Sorry, I deleted my comment as I did get it working using the instructions above :)

Thank you for your work!