Cleaning up top level parcels namespace #1643
Description
Parcels collects most of its functionality into the top level namespace through the use of the parcels/__init__.py file and parcels/<subpackage>/__init__.py files. In these files there are wildcard imports which import from the sub-packages/modules either:
- (if
__all__) items listed in__all__ - (if no
__all__) variables that aren't denoted as private (i.e., all variables not prefixed with an_)
The current setup has a bit of a polluted namespace.
Details
>>> dir(parcels)
['ABC', 'AdvectionAnalytical', 'AdvectionDiffusionEM', 'AdvectionDiffusionM1',
'AdvectionEE', 'AdvectionRK4', 'AdvectionRK45', 'AdvectionRK4_3D',
'AllParcelsErrorCodes', 'AsymmetricAttraction', 'BaseKernel', 'CCompiler',
'CCompiler_SS', 'CGrid', 'Clang_parameters', 'Compiler_parameters', 'ConstNode',
'CurvilinearSGrid', 'CurvilinearZGrid', 'DiffusionUniformKh', 'Field',
'FieldEvalCallNode', 'FieldEvalNode', 'FieldNode', 'FieldOutOfBoundError',
'FieldSamplingError', 'FieldSet', 'FieldSetNode', 'GNUCompiler',
'GNUCompiler_SS', 'GNU_parameters', 'Geographic', 'GeographicPolar',
'GeographicPolarSquare', 'GeographicSquare', 'Grid', 'GridCode', 'GridNode',
'GridSet', 'GridType', 'InteractionKernel', 'IntrinsicNode',
'IntrinsicTransformer', 'JITParticle', 'Kernel', 'KernelError',
'KernelGenerator', 'LoopGenerator', 'MPI', 'MathNode',
'MergeWithNearestNeighbor', 'MinGW_parameters', 'NearestNeighborWithinRange',
'NestedField', 'NestedFieldEvalNode', 'NestedFieldNode',
'NestedVectorFieldEvalNode', 'NestedVectorFieldNode', 'ParcelsRandom',
'ParticleAttributeNode', 'ParticleFile', 'ParticleNode', 'ParticleSet',
'ParticleXiYiZiTiAttributeNode', 'Path', 'PrintNode', 'RandomNode',
'RectilinearSGrid', 'RectilinearZGrid', 'ScipyInteractionParticle',
'ScipyParticle', 'StatusCode', 'StatusCodeNode', 'TimeConverter',
'TimeExtrapolationError', 'Timer', 'TupleSplitter', 'UnitConverter',
'VS_parameters', 'Variable', 'VectorField', 'VectorFieldEvalCallNode',
'VectorFieldEvalNode', 'VectorFieldNode', 'XarrayDecodedFilter', '__builtins__',
'__cached__', '__doc__', '__file__', '__loader__', '__name__', '__package__',
'__path__', '__spec__', '__version__', '_version', 'advection',
'advectiondiffusion', 'application_kernels', 'ast', 'c', 'calcsize',
'cleanup_remove_files', 'cleanup_unload_lib', 'codecompiler', 'codegenerator',
'collections', 'compilation', 'convert_to_flat_array',
'convert_xarray_time_units', 'converters', 'copy', 'datetime',
'download_example_dataset', 'dphidxsi2D_lin', 'dphidxsi3D_lin', 'dxdxsi2D_lin',
'dxdxsi3D_lin', 'exampledata_utils', 'field', 'fieldfilebuffer', 'fieldset',
'get_cache_dir', 'get_data_home', 'get_package_dir', 'gettempdir', 'getuid',
'global_statics', 'grid', 'gridset', 'interaction', 'interactionkernel',
'interpolate', 'interpolation_utils', 'jacobian2D_lin', 'jacobian3D_lin',
'jacobian3D_lin_face', 'kernel', 'length2d_lin_edge', 'list_example_datasets',
'logger', 'loggers', 'math', 'np', 'os', 'particle', 'particledata',
'particlefile', 'particleset', 'phi1D_lin', 'phi1D_quad', 'phi2D_lin',
'phi3D_lin', 'random', 'rng', 'statuscodes', 'subprocess', 'sys', 'time',
'timer', 'tools', 'unitconverters_map', 'version']
Leading to strange behaviour such as
>>> parcels.np.array([1,2,3])
array([1, 2, 3])
I also think stuff like interpolation functions like phi1D_lin being in the top level namespace is a bit excessive, but perhaps that would be something to clean up in v4.
I don't know the best way to fix this is, or what the best practice is on this.