Request: Updated dev guide

Development
1

Seems there is some knowledge that isn’t in the dev guide itself. https://beets.readthedocs.io/en/stable/dev/index.html

The overall principle I would follow is document things unique to beets while give less/no detail on general development / Python development.

If I get a handle on the content and formatting, I can put some of this information into the docs.

  1. How do I run tests?

I got this set up in VS Code but I’m not clear on the relationship between tox and individual Python testing packages. I get that Tox is a meta framework for testing across ex. different platforms but I don’t know what it uses to run actual *test*.py files. Are devs able to replicate the Github actions / test process on their on PCs?

  1. How do I contribute to beets?

In the docs I don’t see any direct reference to how you contribute to the beets core.

  1. Can I install every package called by the test files at once?

Bonus points if I can call this dynamically so the docs are never out of date. I think this is the full list, perfect for requirements.txt. But it was generated from test logs so it could be incomplete.

discogs_client
flask
mock
# for acoustid
pyacoustid
# for mpd
python-mpd2
pylast
requests_oauthlib
responses
xdg
  1. What is a good dev workflow?

Okay, this may be more of a general Python question. I installed an editable clone of beets, per the FAQ, but it feels taped-together. I installed it overtop the old install I had installed the same way and it seems to work for now.

2

The short answer is that yes, running tox is supposed to reproduce exactly what happens on CI. The longer answer is that tox runs commands from tox.ini:

…which are probably best referred to there rather than duplicating in the documentation? That way, we can change them without the risk of the docs getting out of date.

Hmm; this should have been added to the docs in this PR:

But I don’t think it’s showing up? I don’t immediately see why.

The best way is to use tox, which takes care of installing dependencies for you. Another way is to pip install beets[test] or similar.

We do have some instructions in the contributing guide:

3

Thanks. I needed to pip install -U sphinx on WSL Ubuntu before I could run tox.

4

I finally got the whole thing working in a VirtualBox of Lubuntu 20.04. Full test suite is a bit sluggish, as you might expect. I need to add more cores than the default 1 to my VM.

Some pitfalls:

  1. Must install all prerequisite packages. Tox did not manage this for me. pip install beets[test] works. (Not 100% sure on whether to do install -U or without -U. sudo is probably a terrible idea here because it would install system level packages not tracked by your package manager.)
  2. I don’t recommend Windows. WSL is a maybe. (After figuring out #3 it does seem to work… haven’t decided where I’m going to set up shop as a real dev environment.) I have a very bootleg make from Cygwin on my Windows and between Cygwin, pip, and all the dependencies, it seems like a crapshoot getting them all to play nice. Maybe a venv would help?
  3. Had to reset my PATH. Your PATH must contain everything pip installs (ex. flask) and when I ran step 1, my shell didn’t reset to get the new PATH folders in my user folder.
  4. The tox output is not helpful for why it’s failing to run. If you run into issues run it in -vv (or -vvvv) mode, and probably check the /tests/ folder in the beets repo.
1 Like
5

Is it possible to add sphinx (and maybe tox, if it’s not in there already) to the same suite that is installed with pip install beets[test]?

edit: I can’t get tox to run a specific test. The test correctly shows as failed when I run tox on the whole suite.

This was of no use to me. :\ https://stackoverflow.com/questions/35697353/how-to-run-only-one-test-in-tox

I can run python3 -m pytest -q test_files.py which does what I need in this early phase.

1 Like