ENH: Tox as main entry point for development

[FHaase]

So I have been working on issue #23154 trying to setup flake8-rst as additional check for code within documentation.

It's working great, finding multiple places to fix, however in order to test I'm not able to run the appropriate commands.

• created a conda environment
• installed dependencies from ./ci/requirements_dev.txt and ./ci/requirements-optional-conda.txt
• activated pandas-dev environment
• executed python make.py html within ./doc folder

Resulting in

~/.../pandas/core/algorithms.py in _factorize_array(values, na_sentinel, size_hint, na_value)
    472     table = hash_klass(size_hint or len(values))
    473     labels, uniques = table.factorize(values, na_sentinel=na_sentinel,
--> 474                                       na_value=na_value)
    475 
    476     labels = ensure_platform_int(labels)

TypeError: factorize() takes no keyword arguments

So I can't really evaluate weather the changes I am going to make are correct.

Trying to build pandas or running the test suite never worked for me as well. Maybe it's just my own error, but I think there are others getting these issues.

As the project is already featuring tox I'm proposing to enhance tox with all these use-cases so that after a fresh clone of the project someone can just type tox -e docs and tox creates a venv with all required dependencies and runs the build,
tox -e check to run flake8, isort, validate_docstrings.py ...
tox for a complete check of everything -> reducing failing ci-builds

In my opinion this could simplify someones first steps to contribute to pandas. What do you think?

[jorisvandenbossche]

@FHaase regarding the error you get: you need to (re)build the pandas C extensions (python setup.py build_ext --inplace)

[jorisvandenbossche]

Regarding the actual proposal about tox: personally I never used tox, and I also doubt many of the core devs are using it (I think, not sure). As far as I know, it also does not really work with conda? (and conda is currently the main way we recommend to create an environment)

If we want to make certain things easier, I would rather add some commands like make inplace (for rebuilding the c extensions), make check (for code checkers), ... which can be agnostic to the environment / development tools you are using for the rest.

[FHaase]

python setup.py build_ext --inplace helped a lot, however it's still failing:

---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
<ipython-input-90-ec76bd1aa2cb> in <module>
----> 1 avg_weight /= len(x)

NameError: name 'avg_weight' is not defined
  File "<ipython-input-91-204b3859f54f>", line 1
    return pd.Series(['L',avg_weight,True], index=['size', 'weight', 'adult'])
                                                                              ^
SyntaxError: 'return' outside function

<<<-------------------------------------------------------------------------

The respective code at least looks fine to me:

.. ipython:: python

   def GrowUp(x):
      avg_weight =  sum(x[x['size'] == 'S'].weight * 1.5)
      avg_weight += sum(x[x['size'] == 'M'].weight * 1.25)
      avg_weight += sum(x[x['size'] == 'L'].weight)
      avg_weight /= len(x)
      return pd.Series(['L',avg_weight,True], index=['size', 'weight', 'adult'])

   expected_df = gb.apply(GrowUp)

   expected_df

[TomAugspurger]

That's a bug with IPython 7.0. It's fixed on IPython master.

[jbrockmendel]

FWIW I find tox useful for projects with short-running test suites and no formal CI.

Is the existing tox.ini file usable/useful in its current state? Only real opinion here is that it should be either maintained or removed.

[FHaase]

Well it took me quite some time to get the project running. I looked in the contribution-guide and although I thought I followed everything in the guide, however I missed something, had wrong dependencies (IPython) so tests, building the documentation etc. did not run smoothly.

Right now I found:

• ./doc/make.py - has to run in ./doc folder
• ./ci/code_checks.sh - works only when in root directory
• various scripts in root-folder to trigger test-runs.

The question for me is: Which of these scripts are actually usefull to run before creating a PR?
If there was a single file answering all these questions. Taking care of correct dependencies, building the c-extension etc. this process would be more simpler to understand.

Ideally there was a file written in python (easy to understand for devs only knowing python) which defines various tasks [build_doc, build_extension, test_all, test_fast, check] taking care of all steps that are required to predict a running/failing ci-build before actually commiting/opening a PR.
If the ci-builds run by calling tasks of the script it doesn't create duplicate code.

If there wasn't the incompatibility with conda tox would be a great possibility.

Is the existing tox.ini file usable/useful in its current state? Only real opinion here is that it should be either maintained or removed.

I don't think the file is usefull anymore as it didn't change since more than a year and it creates a folder .tox in the root directory with all the dependencies which isn't excluded from flake8 causing it to run for a long time.

[jbrockmendel]

It looks like tox has recently (as in since the last time I looked at the docs) started looking for config in setup.cfg, so if we do choose to keep it, we can still lose the file.

[jorisvandenbossche]

The question for me is: Which of these scripts are actually usefull to run before creating a PR?

We should maybe already start with a better summary checklist in the contributing guidelines of which things to check when submitting a PR / updating a PR.
Because currently, there is a lot of information in there, but probably can easily loose the overview in the long document.

[jbrockmendel]

Closing since we no longer have a tox.ini at all and docstring validation has moved forward elsewhere.