feat: --json --list-sessions

[henryiii]

Closes #658.

No tests yet. Putting out an initial design.

Here's the output on nox itself:

nox --json -l -s cover lint | jq

[
  {
    "session": "cover",
    "name": "cover",
    "description": "Coverage analysis.",
    "python": null,
    "tags": [],
    "call_spec": {}
  },
  {
    "session": "lint",
    "name": "lint",
    "description": "Run pre-commit linting.",
    "python": "3.9",
    "tags": [],
    "call_spec": {}
  }
]

And it can be processed by jq:

$ nox --json -l -s tests | jq '.[].session'
"tests-3.7"
"tests-3.8"
"tests-3.9"
"tests-3.10"
"tests-3.11"

Thoughts?

[henryiii]

Any thoughts on the general design?

[FollowTheProcess]

Hey @henryiii sorry this one slipped by me! I like it and was actually surprised at how little needed to change to support this. For those wondering how it ends up looking:

Just a couple of questions more than anything.

When sessions don't have a python the output from this is null e.g. from our own docs session:

I wonder if there's something more helpful we can put here? This seems to be when we use the nox.session decorator without calling it so Nox uses the python that called it to do the virtualenv, could we populate the JSON python version with the version from sys.version_info? A quick POC on my local copy of your branch seems to work okay:

report.append(
      {
          "python": session.func.python or f"{sys.version_info.major}.{sys.version_info.minor}",
      }
  )

Finally a very minor one but I'm not sure of the usefulness of the name call_spec to anyone other than nox developers. I think a more user friendly term here would be good, something that makes it clearer this is to do with parametrize?

Other than that though this looks great!

[henryiii]

Null output

This can be used to detect when the Python version doesn't matter. I'd assume a user would want to fill nulls with 3.x on GitHub Actions, and possibly something else on other platforms. (I thought about injecting 3.x, but that could be a bit GHA specific, whereas I'd want this to be general? You can always replaced a known, unique string, though, so this wouldn't be too bad.)

I wouldn't want to inject the actual running Python because you lose the info that it doesn't matter, and you might not be running the listing on the same Python as you run the check later - that shouldn't matter.

call_spec

I wasn't sure what to call it and being consistent seemed the simplest thing. ¯\_(ツ)_/¯

[FollowTheProcess]

Ahh yeah good point re. "python doesn't matter"

I wasn't sure what to call it and being consistent seemed the simplest thing

That's fair, naming is hard after all! None of this was a blocker for me, this looks great 👍🏻

[henryiii]

That doesn't mean it has to be named "call_spec", I just was explaining where the name came from. :) If you want to suggest something, go ahead.

[FollowTheProcess]

Well I'm in a similar boat to be honest, I can't really think of a good name either 👀

[FollowTheProcess]

When dumping the JSON is it worth prettying it with indent or something do you think? Obviously computers don't care but it makes it a bit more human readable without using e.g. jq?

[henryiii]

is it worth prettying it with indent

I considered it, in fact I did do that at first, but dropped it when it's so easy to do it with jq, and the point of the output is to be processed, not to be human readable. But this is not something where saving a few whitespace characters matters, so indent is fine too.

My next plan is to try this on a repo somewhere, to see what processing this looks like. I've fixed my blog post's example something like 3-4 times because I missed things. That will probably make good documentation, too. :)

[FollowTheProcess]

Yeah agreed, I think it's fine to leave it out. Even if people pipe it to files as soon as they open them in e.g. VSCode it'll probably format it nicely anyway.

That will probably make good documentation, too. :)

This would be great! If you can find some useful tricks it might be worth making a new recipe in the Cookbook

I'd be interested to see how people might use this actually, it feels like it could be quite powerful in e.g. CI systems but I can't quite think of a use case in anything I'm doing at the moment

[FollowTheProcess]

Where did you get to on this @henryiii? With some tests this should be ready to go as far as I can tell?, would be great to get this in for the next release :)

[henryiii]

Finally tried this out: scikit-build/scikit-build-sample-projects#31 :)

[henryiii]

Okay, unless someone wants something like --format=json instead of --json, this is ready. Probably needs a cookbook example or two eventually.

[FollowTheProcess]

Looks great! Thanks @henryiii