Privatize some plasmapy.particles modules

[namurphy]

This PR makes the following changes to module names:

• plasmapy.particles.parsing → plasmapy.particles._parsing
• plasmapy.particles.elements → plasmapy.particles._elements
• plasmapy.particles.isotopes → plasmapy.particles._isotopes
• plasmapy.particles.special_particles → plasmapy.particles._special_particles

I also made the following changes:

• Dropped the initial underscore of objects within these modules, as suggested by @rocco8773
• Changed the names of some variables to match PEP 8 conventions
• Imported these modules directly rather than the contents of these modules

• I have added a changelog entry for this pull request.

• If adding new functionality, I have added tests and
  docstrings.

• I have fixed any newly failing tests.

[codecov]

Codecov Report

Merging #1440 (d4321cf) into main (f8e3a2a) will decrease coverage by 0.01%.
The diff coverage is 99.27%.

@@            Coverage Diff             @@
##             main    #1440      +/-   ##
==========================================
- Coverage   96.50%   96.49%   -0.02%     
==========================================
  Files          80       80              
  Lines        7848     7847       -1     
==========================================
- Hits         7574     7572       -2     
- Misses        274      275       +1     

Impacted Files	Coverage Δ
plasmapy/particles/__init__.py	96.15% <87.50%> (-3.85%)	⬇️
plasmapy/particles/_elements.py	100.00% <100.00%> (ø)
plasmapy/particles/_factory.py	100.00% <100.00%> (ø)
plasmapy/particles/_isotopes.py	100.00% <100.00%> (ø)
plasmapy/particles/_parsing.py	100.00% <100.00%> (ø)
plasmapy/particles/_special_particles.py	100.00% <100.00%> (ø)
plasmapy/particles/atomic.py	100.00% <100.00%> (ø)
plasmapy/particles/particle_class.py	99.00% <100.00%> (-0.01%)	⬇️

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update f8e3a2a...d4321cf. Read the comment docs.

[namurphy]

This PR changes a lot of lines, but nearly all of the changes are renaming modules, variables, & imports and an occasional trivial suggested refactoring. I think the only substantive change is the removal of an if __name__ == "__main__" block at the end of one file that printed out special particle properties.

[namurphy]

In this PR, I ended up removing the leading underscores from the objects within the newly private modules (i.e., _qwbvdc → qwbvdc). After that I put these objects in __all__, but ended up getting a bunch of documentation build errors after doing that. I ended up changing __all__ to an empty list for each of these modules, which ended up removing the doc build errors.

[rocco8773]

The particle_zoo documentation is a bit odd, since it inherits the docstring from ParticleZoo. Basically it's a variable with a class like documentation, minus the the documentation for the methods. I would consider exposing ParticleZoo to the plasmapy.particles namespace and defining particle_zoo in plasmapy.particles with an appropriate new docstring. I say define particle_zoo in plasmapy.particles because if you define it in _special_particles the docstring won't (at least in my experience) carry over to the instance in plasmapy.particles.

I'd see this looking something like the following in plasampy/particles/__init__.py

from plasmapy.particles._special_particles import ParticleZoo

particle_zoo = ParticleZoo()
"""
Data container for representations of "special" particles, like leptons, baryons, etc.

An instance of `~plasmapy.particles._special_particles.ParticleZoo`.
"""

I do think for completeness, if particle_zoo is in our documentation then it must be accompanied with ParticleZoo.

---

I would also consider having ParticleZoo inherit from collections.UserDict so particle_zoo would become the taxonomy_dict.

[rocco8773]

Since particle_zoo is an instance of a class and thus it has a __doc__ attribute (unlike most variables), think we can still define it in _special_particles. I think it would then have to look like...

In __init__.py

from plasmapy.particles._special_particles import particle_zoo, ParticleZoo

In _special_particles.py

particle_zoo = ParticleZoo()
particle_zoo.__doc__ = """
Data container for representations of "special" particles, like leptons, baryons, etc.

An instance of `~plasmapy.particles._special_particles.ParticleZoo`.
"""

[rocco8773]

Suggested change

	>>> ParticleZoo = ParticleZoo()
	>>> 'e-' in ParticleZoo.leptons
	True
	>>> 'nu_e' in ParticleZoo.antineutrinos
	False
	>>> 'mu+' in ParticleZoo.antiparticles
	True
	>>> par_zoo = ParticleZoo()
	>>> 'e-' in par_zoo.leptons
	True
	>>> 'nu_e' in par_zoo.antineutrinos
	False
	>>> 'mu+' in par_zoo.antiparticles
	True

I only chose par_zoo so there wouldn't be any name shadowing with particle_zoo defined later in the file.

[rocco8773]

In this PR, I ended up removing the leading underscores from the objects within the newly private modules (i.e., _qwbvdc → qwbvdc). After that I put these objects in __all__, but ended up getting a bunch of documentation build errors after doing that. I ended up changing __all__ to an empty list for each of these modules, which ended up removing the doc build errors.

Did you ever push a build with __all__ populated? I tested this out locally and I didn't get any build errors, and I wouldn't expect to get build errors. If there were build errors, then it is likely due to some other structural issue than having the names in __all__.

[rocco8773]

LGTM!!