diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index c5ce4cf7f10..91408fae410 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -72,10 +72,10 @@ repos: args: ['--in-place', '--remove-all-unused-imports', '--remove-unused-variable'] exclude: ".*(.fits|.fts|.fit|.txt|tca.*|extern.*|.rst|.md|__init__.py|sunpy/extern|docs/conf.py)$" - repo: https://github.com/timothycrosley/isort - rev: 4.3.21-2 + rev: 5.1.0 hooks: - id: isort - args: ['-sp','setup.cfg','-rc'] + args: ['--sp','setup.cfg'] exclude: ".*(.fits|.fts|.fit|.txt|tca.*|extern.*|.rst|.md|cm/__init__.py|sunpy/extern|docs/conf.py)$" - repo: https://github.com/pre-commit/pre-commit-hooks rev: v2.4.0 diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 0bd895308fd..2e9cc2cd65b 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -84,6 +84,16 @@ The main one is the SunPy repository with where all the known `issues`_ with Sun Each issue should have a series of labels that provide information about the nature of the issue. If you find an issue you'd like to work on, please make sure to add a comment to let people know that you are working on it! This will make it less likely that effort is duplicated. +.. note:: + + sunpy is open source, under the BSD-2 license, and by contributing you are stating that you have the right to and agree to, have your work distributed under the terms of this license. + + If you work at a university or research institution, you will need to check if you can contribute code you have written at work. + You should start by checking if there is a Open Source Software Policy (e.g., `Standford's policy `__) for your work place. + If not, `OSS-Watch `__ summaries what you will need to check and who to ask, however this is from a UK point of view. + `Standford's guidance `__ for example allows someone to contribute and open source their code. + If you are unsure if your university or institution allows you to contribute under the BSD-2 license, you should contact the relevant department or administrator that deals with copyright. + If you are unsure where to start we suggest the `Good First Issue label`_. These are issues that have been deemed a good way to be eased into SunPy and are achievable with little understanding of the SunPy codebase. Please be aware that this does not mean the issue is "easy", just that you do not need to be aware of the underlying structure of SunPy. diff --git a/docs/conf.py b/docs/conf.py index 02990c93c74..ce7e1d120a6 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -39,12 +39,12 @@ # -- Non stdlib imports -------------------------------------------------------- -import ruamel.yaml as yaml -from sphinx_gallery.sorting import ExplicitOrder -from sphinx_gallery.sorting import ExampleTitleSortKey +import ruamel.yaml as yaml # NOQA +from sphinx_gallery.sorting import ExplicitOrder # NOQA +from sphinx_gallery.sorting import ExampleTitleSortKey # NOQA -import sunpy -from sunpy import __version__ +import sunpy # NOQA +from sunpy import __version__ # NOQA # -- Project information ------------------------------------------------------- @@ -62,7 +62,7 @@ # in the CI, especially RTD. ori_level = sunpy.log.level sunpy.log.setLevel("DEBUG") -import sunpy.data.sample # isort:skip +import sunpy.data.sample # NOQA sunpy.log.setLevel(ori_level) # For the linkcheck @@ -85,29 +85,28 @@ # Suppress warnings about overriding directives as we overload some of the # doctest extensions. -suppress_warnings = ['app.add_directive',] +suppress_warnings = ['app.add_directive', ] # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. extensions = [ + 'matplotlib.sphinxext.plot_directive', + 'sphinx_automodapi.automodapi', + 'sphinx_automodapi.smart_resolver', + 'sphinx_gallery.gen_gallery', 'sphinx.ext.autodoc', - 'sphinx.ext.intersphinx', - 'sphinx.ext.todo', 'sphinx.ext.coverage', - 'sphinx.ext.inheritance_diagram', - 'sphinx.ext.viewcode', - 'sphinx.ext.napoleon', 'sphinx.ext.doctest', + 'sphinx.ext.inheritance_diagram', + 'sphinx.ext.intersphinx', 'sphinx.ext.mathjax', - 'sphinx_automodapi.automodapi', - 'sphinx_automodapi.smart_resolver', - 'sphinx_gallery.gen_gallery', + 'sphinx.ext.napoleon', + 'sphinx.ext.todo', + 'sphinx.ext.viewcode', + 'sunpy.util.sphinx.changelog', 'sunpy.util.sphinx.doctest', - 'matplotlib.sphinxext.plot_directive', - 'sunpy.util.sphinx.minigallery', 'sunpy.util.sphinx.generate', - 'sunpy.util.sphinx.changelog', ] # Add any paths that contain templates here, relative to this directory. @@ -161,7 +160,7 @@ # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. -from sunpy_sphinx_theme.conf import * +from sunpy_sphinx_theme.conf import * # NOQA # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, @@ -202,9 +201,9 @@ 'gallery_dirs': os.path.join('generated', 'gallery'), 'default_thumb_file': os.path.join('logo', 'sunpy_icon_128x128.png'), 'abort_on_example_error': False, - 'plot_gallery': True, + 'plot_gallery': 'True', 'remove_config_comments': True, - 'doc_module': ('sunpy') + 'doc_module': ('sunpy'), } # -- Stability Page ------------------------------------------------------------ @@ -216,6 +215,7 @@ 'sunpy_modules': sunpy_modules } + def rstjinja(app, docname, source): """ Render our pages as a jinja template for fancy templating goodness. @@ -232,7 +232,14 @@ def rstjinja(app, docname, source): # -- Sphinx setup -------------------------------------------------------------- + def setup(app): + # If SunpyDeprecationWarning is raised, we want it to error + import os + import warnings + from sunpy.util.exceptions import SunpyDeprecationWarning + warnings.simplefilter("error", SunpyDeprecationWarning) + os.environ["PYTHONWARNINGS"] = "error::sunpy.util.exceptions.SunpyDeprecationWarning" # Generate the stability page app.connect("source-read", rstjinja) diff --git a/docs/dev_guide/code_standards.rst b/docs/dev_guide/code_standards.rst index 7895f869de3..8292198adaf 100644 --- a/docs/dev_guide/code_standards.rst +++ b/docs/dev_guide/code_standards.rst @@ -52,9 +52,14 @@ Coding Style/Conventions Formatting ========== -We enforce a minimum level of code style and we have tools that will automate this step for you. +We enforce a minimum level of code style with our continuous intergration (the name is ``sunpy.sunpy (python_codestyle [linux]``). +This runs a tool called `https://pre-commit.com/ `__. -First step is to install pre-commit:: +Using "tox" allows you to run these tools without having to setup anything within your own Python virtual environment:: + + $ tox -e codestyle + +If you want to setup the pre-commit locally, you can do the following:: $ pip install pre-commit @@ -62,14 +67,22 @@ Now you can do:: $ pre-commit run --all-files -which will run the tools on all the files and make the necessary adjustments. -This will show up as new changes that you can review before you commit your work. +which will run the tools on all files in the sunpy git repository. +The pre-commit tools can change some of the files, in other cases it will report problems but will require manual correction. +If the pre-commit tool changes any files, they will show up as new changes that will need to be committed. -The other option is to:: +Instead of running the pre-commit command each time you can install the git hook:: $ pre-commit install which installs a command to `.git/hooks/pre-commit` which will run these tools at the time you do ``git commit`` and means you don't have to run the first command each time. +We only suggest doing the install step if you are comfortable with git and the pre-commit tool. + +The settings and tools we use for the pre-commit can be found in the file `.pre-commit-config.yaml` at the root of the sunpy git repository. +Some of the checks are: +* Check (but will not fix) for various PEP8 issues with flake8. +* Sort all imports in any Python files with isort. +* Remove any unused variables or imports with autoflake. Documentation and Testing ========================= diff --git a/docs/dev_guide/documentation.rst b/docs/dev_guide/documentation.rst index 4250d803608..c792ee802fb 100644 --- a/docs/dev_guide/documentation.rst +++ b/docs/dev_guide/documentation.rst @@ -10,25 +10,79 @@ Overview All code must be documented and we follow these style conventions described here: * `numpydoc `_ -* `astropy `_ -We recommend familiarizing yourself with these references. +We recommend familiarizing yourself with this style. -Differences ------------ +Referring to other code +----------------------- -The current differences we have are as follows: +To link to other methods, classes, or modules in sunpy you have to use backticks, for example: -We backtick each type in the documentation strings so that they are interlinked by our documentation builder: +.. code-block:: rst -.. code-block:: python + `sunpy.io.file_tools.read_file` - """ - Parameters - ---------- - x : `type` - Description of parameter x. - """ +generates a link like this: `sunpy.io.file_tools.read_file`. + +We use the sphinx setting ``default_role = 'obj'`` so that you don't have to use qualifiers like ``:class:``, ``:func:``, ``:meth:`` and the like. + +Often, you don't want to show the full package and module name. +As long as the target is unambiguous you can simply leave them out: + +.. code-block:: rst + + `.read_file` + +and the link still works: `.read_file`. + +If there are multiple code elements with the same name (e.g. ``peek()`` is a method in multiple classes), you'll have to extend the definition: + +.. code-block:: rst + + `GenericMap.peek` or `CompositeMap.peek` + +These will show up as `GenericMap.peek` or `CompositeMap.peek`. +To still show only the last segment you can add a tilde as prefix: + +.. code-block:: rst + + `~.GenericMap.peek` or `~.CompositeMap.peek` + +will render as `~.GenericMap.peek` or `~.CompositeMap.peek`. + +Other packages can also be linked via +`intersphinx `_: + +.. code-block:: rst + + `numpy.max` + +will return this link: `numpy.max`. +This works for Python, Numpy and Astropy (full list is in :file:`docs/conf.py`). +If external linking fails, you can check the full list of referenceable objects with the following +commands:: + + $ python -m sphinx.ext.intersphinx 'https://docs.python.org/3/objects.inv' + +If you want to link to a method or function you can add: + +.. code-block:: rst + + :func:`numpy.mean` + +which will render a link and extra brackets :func:`numpy.mean`. +If you decide to use ``:meth:`` instead this will also render extra brackets but will not link in this case. +This is because "numpy.mean" is a function. + +If you link to a method of a class, it will work. + +.. code-block:: rst + + :meth:`numpy.ndarray.mean` + +:meth:`numpy.ndarray.mean` but ``:func:`` will not. + +Never add ``:class:`` this will break the linking. SunPy-Specific Rules -------------------- @@ -44,6 +98,7 @@ SunPy-Specific Rules Documenting Data Sources ---------------------------- + Subclasses of `~sunpy.map.GenericMap` or `~sunpy.timeseries.TimeSeries` must provide a detailed docstring providing an overview of the data source that the object represents. In order to maintain consistency and completeness, the following information must be provided by a data source docstring, if available, and preferably in the following order: @@ -67,7 +122,7 @@ In addition, a reference section must be provided with links to the following re * information to interpret metadata keywords such as FITS header reference * the data archive -An example docstring can be found in the :ref:`Writing a new Instrument Map Class guide`. +An example docstring can be found in the :ref:`Writing a new Instrument Map Class guide `. Sphinx ====== @@ -94,7 +149,7 @@ Sphinx builds documentation iteratively, only adding things that have changed. If you want to build the documentation without building the gallery, i.e. to reduce build times while working on other sections of the documentation you can run:: - $ tox -e build_docs -- -D plot_gallery=0 + $ tox -e build_docs -- -D plot_gallery=False If you'd like to start from scratch (i.e., remove the tox cache) then run:: diff --git a/docs/dev_guide/images/azure_check_pr.png b/docs/dev_guide/images/azure_check_pr.png new file mode 100644 index 00000000000..801325732cc Binary files /dev/null and b/docs/dev_guide/images/azure_check_pr.png differ diff --git a/docs/dev_guide/images/azure_goto.png b/docs/dev_guide/images/azure_goto.png new file mode 100644 index 00000000000..2307559da5f Binary files /dev/null and b/docs/dev_guide/images/azure_goto.png differ diff --git a/docs/dev_guide/images/azure_steps_in_job.png b/docs/dev_guide/images/azure_steps_in_job.png new file mode 100644 index 00000000000..d9e02d82ae1 Binary files /dev/null and b/docs/dev_guide/images/azure_steps_in_job.png differ diff --git a/docs/dev_guide/images/azure_summary_check.png b/docs/dev_guide/images/azure_summary_check.png new file mode 100644 index 00000000000..e32470cb0b6 Binary files /dev/null and b/docs/dev_guide/images/azure_summary_check.png differ diff --git a/docs/dev_guide/images/checks.png b/docs/dev_guide/images/checks.png new file mode 100644 index 00000000000..701979f15c0 Binary files /dev/null and b/docs/dev_guide/images/checks.png differ diff --git a/docs/dev_guide/images/checks_pr.png b/docs/dev_guide/images/checks_pr.png new file mode 100644 index 00000000000..c1d63219b21 Binary files /dev/null and b/docs/dev_guide/images/checks_pr.png differ diff --git a/docs/dev_guide/images/list_of_azure_checks.png b/docs/dev_guide/images/list_of_azure_checks.png new file mode 100644 index 00000000000..841c89cf9bd Binary files /dev/null and b/docs/dev_guide/images/list_of_azure_checks.png differ diff --git a/docs/dev_guide/pr_review_procedure.rst b/docs/dev_guide/pr_review_procedure.rst index 0b3aa5fb788..b8a26debdd9 100644 --- a/docs/dev_guide/pr_review_procedure.rst +++ b/docs/dev_guide/pr_review_procedure.rst @@ -35,17 +35,121 @@ It is important that approval for merging the PR is done on the comment thread, Continuous Integration ====================== -Currently we have a variety of services that respond or activate on an opened pull request: +Currently we have a variety of services that respond or activate on an opened pull request. -* `pep8speaks `_: Performs a PEP8 check on any submitted code. +Comments from bots: -* `CircleCi `_: Tests to see if sunpy installs, builds the documentation and runs the figure tests. +* `pep8speaks `_: Performs a PEP8 check on any submitted code. This is updated as the code changes. -* Giles: Returns a link if the documentation builds successfully. +Checks that appear at the bottom of a pull request: -* `Azure Pipelines `_: Runs our test suite on all three operating systems. +.. image:: images/checks_pr.png + :width: 600 + :alt: PR checks -* `CodeCov `_: Checks how many lines of the code lack test coverage. +or at the top under the "Checks" tab: + +.. image:: images/checks.png + :width: 600 + :alt: PR checks tab + +* `figure-tests (CircleCi) `_: Runs two figure tests environments ("py38-figure", "py37-figure-devdeps"). + +* figure_report/figure_tests (Giles): Show the final results of the figure tests. + +* figure_report_devdeps (Giles): Show the final results of the figure tests using development packages. + +* changelog: absent | found (Giles): If a changelog is needed, this will check and will pass if a changelog with the correct number is found. + +* milestone: absent | present (Giles): Will check that the pull request has a milestone assigned. + +* `docs/readthedocs.org:sunpy (Read the Docs) `_: This builds our documentation. + +* `sunpy.sunpy (Azure Pipelines) `_: Runs our test suite on all three operating systems. + There are 10 separate checks for this. + +* `codecov/patch (CodeCov) `_: Checks how many lines of the code lack test coverage for the submitted code. + +* `codecov/project (CodeCov) `_: Checks how many lines of the code lack test coverage in sunpy overall. + +It is common to see some of these checks fail. +This can be happen to due a change that has broken a test or a remote server that we use has failed. +Therefore it is important to check why a task failed and if has a pre-existing issue, it can be safe to ignore on that pull request. +However, you should try to ensure that as many checks pass before merging. + +Understanding Azure Pipelines +----------------------------- + +The vast majority of our tests are run on Azure Pipelines and this means you might have to navigate to the results if you want to check why the tests failed. + +The Azure checks on GitHub manifest: + +.. image:: images/azure_check_pr.png + :width: 600 + :alt: PR checks tab + +This is the main form and there will be one per Azure job ran and a summary one just called "sunpy.sunpy". +The details text will redirect you to the "Check" tab. + +Doing so will show: + +.. image:: images/azure_summary_check.png + :width: 600 + :alt: Summary of Azure outputs on Checks tab + +You get some statistics that you don't need to worry about and then a series of boxes under the "ANNOTATIONS" heading. +Unfortunately, when a Azure step fails you sometimes will get "Bash exited with code '1'." which means you have to go to the page to see what happened. +If the failure is due to a test, you will get a selection of test outputs under this heading. + +On the left you should see the entire list of Azure checks. + +You can go to a failing check and you will see: + +.. image:: images/azure_goto.png + :width: 600 + :alt: Go to Azure Pipelines + +which will take you to the Azure Pipelines website. +This will load up the following: + +.. image:: images/azure_steps_in_job.png + :width: 600 + :alt: Build steps in Azure + +Here you can see each step that is undertaken during a job on Azure. +Normally the "Running tox" should be red if the tests have failed. +You will want to click on this which will load up the output from the test suite. + +Our test suite is quite verbose so there is a lot of text loaded. +The important bits of information should be at the bottom as "pytest" prints out a summary at the end. + +.. code:: bash + + ============================================================================= short test summary info ============================================================================= + SKIPPED [1] d:\a\1\s\.tox\py37\lib\site-packages\pytest_doctestplus\plugin.py:178: unable to import module local('d:\\a\\1\\s\\.tox\\py37\\lib\\site-packages\\sunpy\\io\\setup_package.py') + SKIPPED [213] d:\a\1\s\.tox\py37\lib\site-packages\pytest_remotedata\plugin.py:87: need --remote-data option to run + SKIPPED [18] d:\a\1\s\.tox\py37\lib\site-packages\_pytest\doctest.py:387: all tests skipped by +SKIP option + SKIPPED [1] .tox\py37\lib\site-packages\sunpy\map\sources\tests\test_source_type.py:21: Glymur can not be imported. + SKIPPED [1] .tox\py37\lib\site-packages\sunpy\map\sources\tests\test_source_type.py:30: Glymur can not be imported. + SKIPPED [1] .tox\py37\lib\site-packages\sunpy\io\tests\test_ana.py:22: ANA is not available. + SKIPPED [1] .tox\py37\lib\site-packages\sunpy\io\tests\test_ana.py:31: ANA is not available. + SKIPPED [1] .tox\py37\lib\site-packages\sunpy\io\tests\test_ana.py:40: ANA is not available. + SKIPPED [1] .tox\py37\lib\site-packages\sunpy\io\tests\test_ana.py:49: ANA is not available. + SKIPPED [1] .tox\py37\lib\site-packages\sunpy\io\tests\test_ana.py:58: ANA is not available. + SKIPPED [1] .tox\py37\lib\site-packages\sunpy\io\tests\test_ana.py:67: ANA is not available. + SKIPPED [1] .tox\py37\lib\site-packages\sunpy\io\tests\test_filetools.py:54: Glymur can not be imported. + SKIPPED [1] .tox\py37\lib\site-packages\sunpy\io\tests\test_filetools.py:73: Glymur can not be imported. + SKIPPED [1] .tox\py37\lib\site-packages\sunpy\io\tests\test_filetools.py:106: ANA is not available. + SKIPPED [1] .tox\py37\lib\site-packages\sunpy\io\tests\test_filetools.py:115: ANA is not available. + SKIPPED [1] .tox\py37\lib\site-packages\sunpy\io\tests\test_filetools.py:122: ANA is not available. + SKIPPED [1] .tox\py37\lib\site-packages\sunpy\io\tests\test_jp2.py:11: Glymur can not be imported. + SKIPPED [1] .tox\py37\lib\site-packages\sunpy\io\tests\test_jp2.py:21: Glymur can not be imported. + SKIPPED [1] .tox\py37\lib\site-packages\sunpy\io\tests\test_jp2.py:31: Glymur can not be imported. + SKIPPED [1] .tox\py37\lib\site-packages\sunpy\net\tests\test_fido.py:298: Windows. + SKIPPED [1] .tox\py37\lib\site-packages\sunpy\net\tests\test_helioviewer.py:90: Glymur can not be imported. + FAILED ..\..\.tox\py37\lib\site-packages\sunpy\timeseries\sources\noaa.py::sunpy.timeseries.sources.noaa.NOAAGoesSXRTimeSeries + +You can then search for the name of the test and it should find the full output from the failed test. SunPy GitHub Groups =================== @@ -68,8 +172,6 @@ The membership of this group is at the discretion of the Lead Developer, but sha This group has `subgroups `__ for each section of the repository that has `maintainers `__. The members of these groups will automatically be requested to review all PRs which change files in that subpackage. - - SunPy Developers ---------------- diff --git a/docs/dev_guide/tests.rst b/docs/dev_guide/tests.rst index 9a2ca3a35e2..28c61f5af97 100644 --- a/docs/dev_guide/tests.rst +++ b/docs/dev_guide/tests.rst @@ -43,7 +43,7 @@ Each method uses the widely-used ``pytest`` framework and are detailed below. The primary method is to use `tox`_, which is a generic virtualenv management and test command line tool. We have several environments within our "tox.ini" file and you can list them:: - $ tox -l + $ tox -v -l Then you can run any of them doing:: diff --git a/docs/guide/installation/advanced.rst b/docs/guide/installation/advanced.rst index 6e1403212ea..dba0c60a2b1 100644 --- a/docs/guide/installation/advanced.rst +++ b/docs/guide/installation/advanced.rst @@ -3,92 +3,92 @@ Advanced Installation Instructions ********************************** -This document provides details on things you need to know to install and manage your own scientific Python + SunPy installation. -If you have never installed or used scientific Python we recommend that you follow the :ref:`Anaconda installation instructions `. +This document provides details on things you need to know to install and manage your own scientific Python + sunpy installation. +If you have never installed or used scientific Python we recommend that you follow the :ref:`Miniconda installation instructions `. -Installing SunPy on top of an existing Scientific Python Environment +Installing sunpy on top of an existing Scientific Python Environment ==================================================================== -These instructions assume you have a scientific Python distribution with access to the `pip` command installed. +These instructions assume you have a scientific Python distribution with access to the ``pip`` command installed. + +.. warning:: + Users of the Miniconda python distribution should follow the instructions for :ref:`main-install`. Prerequisites ------------- -You will need a compiler suite and the development headers for Python and numpy in order to build SunPy. -On Linux, using the package manager for your distribution will usually be the easiest route, while on MacOS X you will need the XCode command line tools. +You will need a C compiler (e.g., ``gcc`` or ``clang``) to be installed as we have a C library within sunpy that is built at install time. -The `instructions for building Numpy from source `_ are also a good resource for setting up your environment to build Python packages. +If you use Miniconda, you can get these compilers from there. +On Linux, using the package manager for your distribution will usually be the easiest route, while on MacOS X you will need the XCode command line tools. Using `pip` ----------- -.. warning:: - Users of the Anaconda python distribution should follow the instructions for :ref:`anaconda_install`. +.. note:: + We strongly recommend using a `Python virtual environment `__ so any Python packages you install will be kept separate from your Operating System Python. + You can use Conda as a virtual environment manager instead of one of the more common Python virtual environment managers. -SunPy consists of many submodules that each have their own requirements. -You do not need to fulfil all the requirements if you only intend on using parts of SunPy. +sunpy consists of many submodules that each have their own requirements. +You do not need to fulfil all the requirements if you only intend on using parts of sunpy. It is however *strongly* recommended to have all the dependencies installed (with the potential exception of ``glymur``). There are multiple options depending on how many optional dependencies you want to install: -To install SunPy with ``pip`` including optional dependencies (recommended), simply run:: +To install sunpy with ``pip`` including optional dependencies (recommended), simply run:: pip install sunpy[all] -To install SunPy with no optional dependencies:: +To install sunpy with no optional dependencies:: pip install sunpy -To install SunPy with net-based dependencies:: +To install sunpy with net-based dependencies:: pip install sunpy[net] -To install SunPy with database dependencies:: +To install sunpy with database dependencies:: pip install sunpy[database] Other available options are: ``[image]``, ``[jpeg2000]``, ``[asdf]``, ``[tests]`` and ``[docs]``. -The entire list of options are compassed by a ``[dev]`` option, so you can do:: +The entire list of options are encompassed by a ``[dev]`` option, so you can do:: pip install sunpy[dev] -to install all the packages needed to run and develop SunPy. - -.. note:: - You will need a C compiler (e.g., ``gcc`` or ``clang``) to be installed. - If you use anaconda, you can get these packages from there instead. +to install all the packages needed to run and develop sunpy. +However if you want to develop sunpy we would strongly recommend reading :ref:`newcomers`. .. note:: If you get a ``PermissionError`` this means that you do not have the required administrative access to install new packages to your Python installation. In this case you may consider using the ``--user`` option to install the package into your home directory. You can read more about how to do this in the `pip documentation `__. - Alternatively, if you intend to do development on other software that uses SunPy, such as an affiliated package, consider installing SunPy into a `virtualenv `__. - - Do **not** install SunPy or other third-party packages using ``sudo`` unless you are fully aware of the risks. + Do **not** install sunpy or other third-party packages using ``sudo``. .. _testing-sunpy: -Testing SunPy +Testing sunpy ************* .. warning:: The tests will fail if you do not install all the optional dependencies. + If you have installed sunpy with conda-forge, you will be missing the ``pytest-mock`` package which will cause the test suite to fail. -The easiest way to test your installed version of SunPy is running correctly is to use the :func:`sunpy.self_test()` function:: +The easiest way to test your installed version of sunpy is running correctly is to use the :func:`sunpy.self_test()` function:: import sunpy sunpy.self_test() -which will run many of the SunPy tests. +which will run many of the sunpy tests. -The tests should run and print out any failures, which you can report at the `SunPy issue tracker `__. +The tests should run and print out any failures, which you can report at the `sunpy issue tracker `__. -SunPy's Requirements +sunpy's Requirements ******************** -SunPy has the following strict requirements: +sunpy has the following strict requirements: - `Python `__ 3.7.x or later. @@ -104,9 +104,13 @@ SunPy has the following strict requirements: - `matplotlib `__ 2.2.2 or later. -SunPy also depends on other packages for optional features. -However, note that these only need to be installed if those particular features are needed. -SunPy will import even if these dependencies are not installed. +These packages that will be installed as dependencies by default and are the ones required to import the core datatypes `~sunpy.map`, `~sunpy.timeseries` and `~sunpy.spectra`. + +sunpy also depends on other packages for optional features. +However, note that these only need to be installed if those you have requested them when you pip install them. +They are installed by default if you use the conda-forge sunpy package. + +The following optional packages are: - `sqlalchemy `__: For the `~sunpy.database` package. @@ -138,8 +142,3 @@ To run the tests: - `pytest-cov `__. - `pytest-mock `__. - -The packages that will be installed as dependencies by default and are the ones -required to import the core datatypes `~sunpy.map`, `~sunpy.timeseries` and -`~sunpy.spectra`. These are the strict requirements and the following optional -packages: diff --git a/docs/guide/installation/index.rst b/docs/guide/installation/index.rst index 4fb37667de6..9c87b144e82 100644 --- a/docs/guide/installation/index.rst +++ b/docs/guide/installation/index.rst @@ -21,22 +21,24 @@ Installing Scientific Python and sunpy sunpy is part of the wider ecosystem of scientific Python packages for solar physics. Therefore a working sunpy installation is more about installing the scientific Python ecosystem than sunpy itself. -If you do not currently have a working scientific Python distribution this guide will set you up with the Anaconda -scientific Python distribution, which makes it easy to install and manage your scientific Python packages. +If you do not currently have a working scientific Python distribution this guide will set you up with the Miniconda, which makes it easy to install and manage your scientific Python packages. Other options are listed later in the :ref:`advanced-install` section. -To install the Anaconda Python distribution follow the instructions at -`here `__. -Although Anaconda makes it simple to switch between Python versions, we recommend that new users install -the latest Python 3.x version of Anaconda as SunPy only supports Python 3.7+. +To install the Miniconda Python distribution follow the instructions at +`here `__. +Although Miniconda makes it simple to switch between Python versions, we recommend that new users install +the latest Python 3.x version of Miniconda as SunPy only supports Python 3.7+. -Installing sunpy using Anaconda -------------------------------- +The reason we choose Miniconda over Anaconda, is mainly due to the size as Anaconda comes with a full install of packages you probably do not need and this way you have more direct control over what has been installed into your Python virtual environment. -To install SunPy launch a system command prompt or the 'Anaconda Command Prompt' (under Windows). +Installing sunpy using Miniconda +-------------------------------- + +To install SunPy launch a system command prompt or the 'Anaconda Prompt' (under Windows). First configure conda for sunpy downloads:: conda config --add channels conda-forge + conda config --set channel_priority strict to install sunpy:: @@ -52,11 +54,10 @@ You can update to the latest version by running:: conda update sunpy - Advanced sunpy Installation =========================== -If you do not wish to use Anaconda to install Scientific Python or you already have a scientific Python +If you do not wish to use Miniconda to install Scientific Python or you already have a scientific Python installation there are other options for installing SunPy: .. toctree:: diff --git a/examples/computer_vision_techniques/loop_edge_enhance.py b/examples/computer_vision_techniques/loop_edge_enhance.py index e16a8eb767f..bf07dec41b2 100644 --- a/examples/computer_vision_techniques/loop_edge_enhance.py +++ b/examples/computer_vision_techniques/loop_edge_enhance.py @@ -21,7 +21,7 @@ aia = sunpy.map.Map(AIA_171_IMAGE) bottom_left = SkyCoord(750 * u.arcsec, -200 * u.arcsec, frame=aia.coordinate_frame) top_right = SkyCoord(1500 * u.arcsec, 550 * u.arcsec, frame=aia.coordinate_frame) -aia_smap = aia.submap(bottom_left, top_right=top_right) +aia_smap = aia.submap(bottom_left, top_right) ############################################################################### # Next we apply an edge enhance filter to the data in both x and y directions diff --git a/examples/map/map_data_histogram.py b/examples/map/map_data_histogram.py index ada98a36763..a18e8866b90 100644 --- a/examples/map/map_data_histogram.py +++ b/examples/map/map_data_histogram.py @@ -21,7 +21,7 @@ aia = sunpy.map.Map(AIA_171_IMAGE) bottom_left = SkyCoord(-300 * u.arcsec, 0 * u.arcsec, frame=aia.coordinate_frame) top_right = SkyCoord(100 * u.arcsec, 400 * u.arcsec, frame=aia.coordinate_frame) -aia_smap = aia.submap(bottom_left, top_right=top_right) +aia_smap = aia.submap(bottom_left, top_right) aia_smap.plot() ############################################################################### diff --git a/examples/plotting/skip_magnetogram_active_regions.py b/examples/plotting/magnetogram_active_regions.py similarity index 100% rename from examples/plotting/skip_magnetogram_active_regions.py rename to examples/plotting/magnetogram_active_regions.py diff --git a/examples/time_series/skip_timeseries_example.py b/examples/time_series/timeseries_example.py similarity index 100% rename from examples/time_series/skip_timeseries_example.py rename to examples/time_series/timeseries_example.py diff --git a/setup.cfg b/setup.cfg index b56e3cbcb1f..78f0b2ffbee 100644 --- a/setup.cfg +++ b/setup.cfg @@ -62,7 +62,7 @@ tests = docs = sphinx>=2 sphinx-automodapi - sphinx-gallery + sphinx-gallery>=0.7.0 # First to include the mini-galleries directive sunpy-sphinx-theme ruamel.yaml towncrier @@ -122,12 +122,10 @@ default_section = THIRDPARTY include_trailing_comma = True known_astropy = astropy, asdf known_first_party = sunpy -length_sort = False -length_sort_stdlib = True +length_sort_sections=stdlib line_length = 110 multi_line_output = 3 no_lines_before = LOCALFOLDER -not_skip = __init__.py sections = STDLIB, THIRDPARTY, ASTROPY, FIRSTPARTY, LOCALFOLDER [coverage:run] diff --git a/setup.py b/setup.py index 003b4e977f0..0f140b5131d 100755 --- a/setup.py +++ b/setup.py @@ -14,7 +14,7 @@ Running tests is no longer done using 'python setup.py test'. Instead you will need to run: - tox -e offline + tox -e py38 if you don't already have tox installed, you can install it with: pip install tox if you only want to run part of the test suite, you can also use pytest directly with: diff --git a/sunpy/__init__.py b/sunpy/__init__.py index 08e74739602..a12a0e8e7d6 100644 --- a/sunpy/__init__.py +++ b/sunpy/__init__.py @@ -38,6 +38,7 @@ class UnsupportedPythonError(Exception): def _get_bibtex(): import textwrap + # Set the bibtex entry to the article referenced in CITATION.rst citation_file = os.path.join(os.path.dirname(__file__), 'CITATION.rst') diff --git a/sunpy/conftest.py b/sunpy/conftest.py index 4e91a890028..9938b541212 100644 --- a/sunpy/conftest.py +++ b/sunpy/conftest.py @@ -65,9 +65,10 @@ def sunpy_cache(mocker, tmp_path): remote requests. """ from types import MethodType + from sunpy.data.data_manager.cache import Cache - from sunpy.data.data_manager.storage import InMemStorage from sunpy.data.data_manager.downloader import ParfiveDownloader + from sunpy.data.data_manager.storage import InMemStorage cache = Cache( ParfiveDownloader(), InMemStorage(), @@ -145,7 +146,7 @@ def pytest_unconfigure(config): Turn on internet when generating the figure comparison webpage. """ if HAVE_REMOTEDATA: - from pytest_remotedata.disable_internet import turn_on_internet, turn_off_internet + from pytest_remotedata.disable_internet import turn_off_internet, turn_on_internet else: def turn_on_internet(): pass def turn_off_internet(): pass diff --git a/sunpy/data/_sample.py b/sunpy/data/_sample.py index 9af3562a137..7592dbbf572 100644 --- a/sunpy/data/_sample.py +++ b/sunpy/data/_sample.py @@ -92,8 +92,12 @@ def download_sample_data(overwrite=False): else: dl.enqueue_file(url, filename=fname) + # Increase timeout. + timeout = {"total": 10 * 60, + "sock_read": 5*60} + if dl.queued_downloads: - results = dl.download() + results = dl.download(timeouts=timeout) else: return already_downloaded @@ -102,21 +106,19 @@ def download_sample_data(overwrite=False): else: log.info('Failed to download one or more sample data files, retrying with a mirror.') - for retry_url in _base_urls[1:]: - for i, err in enumerate(results.errors): - file_name = err.filepath_partial().name - log.debug( - f"Failed to download {_sample_files[file_name]} from {err.url}: {err.exception}") - # Overwrite the parfive error to change the url to a mirror - new_url = urljoin(retry_url, file_name) - results._errors[i] = _error(err.filepath_partial, - new_url, - err.exception) - - results = dl.retry(results) - - if not results.errors: - return results + # Try next URL. + new_dl = Downloader(overwrite=True) + for err in results.errors: + file_name = err.filepath_partial().name + log.debug(f"Failed to download {_sample_files[file_name]} from {err.url}: {err.exception}") + # Update the url to a mirror and requeue the file. + new_url = urljoin(_base_urls[1], file_name) + log.debug(f"Will redownload using {new_url}") + new_dl.enqueue_file(new_url, filename=sampledata_dir/file_name) + results = new_dl.download(timeouts=timeout) + + if not results.errors: + return results for err in results.errors: file_name = err.filepath_partial().name diff --git a/sunpy/time/timerange.py b/sunpy/time/timerange.py index b052ef3f1be..129bae3bbdf 100644 --- a/sunpy/time/timerange.py +++ b/sunpy/time/timerange.py @@ -26,6 +26,9 @@ class TimeRange: Regardless of how a `sunpy.time.TimeRange` is constructed it will always provide a positive time range where the start time is before the end time. + `sunpy.time.TimeRange.__contains__` allows you to check if a time is within the + time range you have created. Please see the example section below. + Parameters ---------- a : {parse_time_types} @@ -54,6 +57,9 @@ class TimeRange: 576000.0 minutes or 34560000.0 seconds + >>> # You can also check if a time is within the time range. + >>> '2010/03/04 00:10' in time_range + True """ def __init__(self, a, b=None, format=None): diff --git a/sunpy/timeseries/sources/eve.py b/sunpy/timeseries/sources/eve.py index 3865883a091..9610526a60c 100644 --- a/sunpy/timeseries/sources/eve.py +++ b/sunpy/timeseries/sources/eve.py @@ -178,13 +178,12 @@ def peek(self, column=None, **kwargs): """ Plots the time series in a new figure. An example is shown below: - .. - .. plot:: + .. plot:: - import sunpy.timeseries - from sunpy.data.sample import EVE_TIMESERIES - eve = sunpy.timeseries.TimeSeries(EVE_TIMESERIES, source='eve') - eve.peek(subplots=True) + import sunpy.timeseries + from sunpy.data.sample import EVE_TIMESERIES + eve = sunpy.timeseries.TimeSeries(EVE_TIMESERIES, source='eve') + eve.peek(subplots=True) Parameters ---------- diff --git a/sunpy/timeseries/timeseriesbase.py b/sunpy/timeseries/timeseriesbase.py index 1134af0d483..8dc0b3a6550 100644 --- a/sunpy/timeseries/timeseriesbase.py +++ b/sunpy/timeseries/timeseriesbase.py @@ -429,6 +429,7 @@ def plot(self, axes=None, **plot_args): The plot axes. """ import matplotlib.pyplot as plt + # Get current axes if axes is None: axes = plt.gca() @@ -450,6 +451,7 @@ def peek(self, **kwargs): Any additional plot arguments that should be used when plotting. """ import matplotlib.pyplot as plt + # Check we have a timeseries valid for plotting self._validate_data_for_plotting() diff --git a/sunpy/util/exceptions.py b/sunpy/util/exceptions.py index 84e1112d9c7..be067b9bd07 100644 --- a/sunpy/util/exceptions.py +++ b/sunpy/util/exceptions.py @@ -5,13 +5,11 @@ but rather in the particular package. """ -from astropy.utils.exceptions import AstropyWarning - __all__ = ["SunpyWarning", "SunpyUserWarning", "SunpyDeprecationWarning", "SunpyPendingDeprecationWarning"] -class SunpyWarning(AstropyWarning): +class SunpyWarning(Warning): """ The base warning class from which all Sunpy warnings should inherit. diff --git a/sunpy/util/sphinx/minigallery.py b/sunpy/util/sphinx/minigallery.py deleted file mode 100644 index aca75a06964..00000000000 --- a/sunpy/util/sphinx/minigallery.py +++ /dev/null @@ -1,58 +0,0 @@ -import os - -import sphinx.util.docutils as sphinx_docutils -from docutils import statemachine -from docutils.io import FileInput -from docutils.parsers.rst import Directive - -__all__ = ['MiniGallery'] - - -class MiniGallery(Directive): - """ - Custom directive to insert a mini-gallery - - The required argument is the qualified name of the object. The mini-gallery will be the subset - of gallery examples that make use of that object (from that specific namespace). There can be - more than one object named, separated by spaces. - """ - required_arguments = 1 - optional_arguments = 0 - final_argument_whitespace = True - - def run(self): - # Respect the same disabling options as the ``raw`` directive - if (not self.state.document.settings.raw_enabled - or not self.state.document.settings.file_insertion_enabled): - raise self.warning('"%s" directive disabled.' % self.name) - - obj_list = self.arguments[0].split() - - # Concatenate the backreferences file(s) - lines = [] - for obj in obj_list: - path = os.path.join(os.getcwd(), 'generated', 'modules', f'{obj}.examples') - lines += (FileInput(source_path=path).readlines())[5:] # slice removes heading - - # Append the end for the gallery - lines += ['\n', - '.. raw:: html\n', - '\n', - '
\n'] - text = ''.join(lines) - - include_lines = statemachine.string2lines(text, convert_whitespace=True) - self.state_machine.insert_input(include_lines, path) - - return [] - - -def setup(app): - # If a minigallery directive has already been registered, do nothing. - # It's probably that we are on a version of sphinx-gallery with the directive - if sphinx_docutils.is_directive_registered("minigallery"): - print("Not using sunpy.util.sphinx.minigallery as a minigallery " - "directive has already been registered.") - return - - app.add_directive('minigallery', MiniGallery) diff --git a/tools/unify_section_headings.py b/tools/unify_section_headings.py index 08b031f96f7..9045c7aa852 100755 --- a/tools/unify_section_headings.py +++ b/tools/unify_section_headings.py @@ -63,8 +63,8 @@ def replace_header_chars(filename): if __name__ == "__main__": - from pathlib import Path from glob import glob + from pathlib import Path here = Path(__file__).parent.absolute() rst_files = glob(str(here/Path("../docs/**/*rst")), recursive=True) [replace_header_chars(filename) for filename in rst_files] diff --git a/tox.ini b/tox.ini index 1c3f55176bd..4977760da8c 100644 --- a/tox.ini +++ b/tox.ini @@ -21,12 +21,12 @@ changedir = .tmp/{envname} # see a list of example environments that can be run, along with a description, # run: # -# tox -l -v +# tox -v -l # description = - run tests - devdeps: with the latest developer version of key dependencies + runs the test suite oldestdeps: with the oldest supported version of key dependencies + devdeps: with the latest developer version of key dependencies online: that require remote data hypothesis: using hypothesis (both offline and online) figure: runs the figure test suite.