diff --git a/docs/source/api_docs.rst b/docs/source/api_docs.rst deleted file mode 100644 index 73d9da6dc..000000000 --- a/docs/source/api_docs.rst +++ /dev/null @@ -1,7 +0,0 @@ -Preview Image Test -================== -.. automodapi:: jwql.preview_image.preview_image - -Utils Test -========== -.. automodapi:: jwql.utils.utils diff --git a/docs/source/conf.py b/docs/source/conf.py index c4c75e108..0aab6915b 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -74,10 +74,14 @@ # Usually you set "language" from the command line for these cases. language = None +# This is a fix for warnings because of sphinx-autodoc interaction for classes, however it removes +# method table from the docs. +numpydoc_show_class_members = False + # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. # This patterns also effect to html_static_path and html_extra_path -exclude_patterns = [] +exclude_patterns = ['api/*.rst'] # The name of the Pygments (syntax highlighting) style to use. pygments_style = 'sphinx' @@ -86,6 +90,7 @@ todo_include_todos = False + # -- Options for HTML output ---------------------------------------------- # The theme to use for HTML and HTML Help pages. See the documentation for diff --git a/docs/source/index.rst b/docs/source/index.rst index 4c3820628..d1890cc2a 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -9,7 +9,7 @@ Welcome to jwql's documentation! General JWQL description here. .. toctree:: - :maxdepth: 2 + :maxdepth: 1 :caption: Contents: API documentation @@ -19,7 +19,10 @@ API documentation :maxdepth: 1 :caption: Contents: - api_docs.rst + permissions.rst + preview_image.rst + utils.rst + tests.rst Indices and tables diff --git a/docs/source/permissions.rst b/docs/source/permissions.rst new file mode 100644 index 000000000..08bddb3e6 --- /dev/null +++ b/docs/source/permissions.rst @@ -0,0 +1,7 @@ +*********** +permissions +*********** + +.. automodule:: jwql.permissions.permissions + :members: + :undoc-members: diff --git a/docs/source/preview_image.rst b/docs/source/preview_image.rst new file mode 100644 index 000000000..8dae4ccb3 --- /dev/null +++ b/docs/source/preview_image.rst @@ -0,0 +1,7 @@ +************* +preview_image +************* + +.. automodule:: jwql.preview_image.preview_image + :members: + :undoc-members: diff --git a/docs/source/tests.rst b/docs/source/tests.rst new file mode 100644 index 000000000..175c9299b --- /dev/null +++ b/docs/source/tests.rst @@ -0,0 +1,6 @@ +***** +tests +***** + +.. automodule:: jwql.tests.test_permissions + :members: diff --git a/docs/source/utils.rst b/docs/source/utils.rst new file mode 100644 index 000000000..2abe92d9c --- /dev/null +++ b/docs/source/utils.rst @@ -0,0 +1,6 @@ +***** +utils +***** + +.. automodule:: jwql.utils.utils + :members: diff --git a/jwql/permissions/permissions.py b/jwql/permissions/permissions.py index 5c8b1aa45..5e6294c7e 100644 --- a/jwql/permissions/permissions.py +++ b/jwql/permissions/permissions.py @@ -1,13 +1,13 @@ #! /usr/bin/env python -"""Permissions module for managing file permissions for jwql. +"""Permissions module for managing file permissions for ``jwql``. -This module provides jwql with functions to inspect and set file +This module provides ``jwql`` with functions to inspect and set file permissions. -The module takes as input a path to a file or directory, checks - whether the owner of the file is the jwql admin account, and if - so, (1) set the permissions appropriately, and (2) set the - group membership appropriately. +The module takes as input a path to a file or directory, checks whether +the owner of the file is the ``jwql`` admin account, and if so, (1) set +the permissions appropriately, and (2) set the group membership +appropriately. Authors ------- @@ -20,51 +20,56 @@ This module can be imported and used with :: + from jwql.permissions import permissions permissions.set_permissions(pathname) Required arguments: - ``pathname`` - Directory or file for which the default permissions should be set + ``pathname`` - Directory or file for which the default permissions + should be set Notes ----- - Permissions are set and read using the stat module, - see https://docs.python.org/3/library/stat.html - Below is a list with the relevant stat attribute names, - integer, octal, and string representations. - - stat_key stat_mode stat_mode_octal stat_mode_string - -------- --------- --------------- ---------------- - S_IFPORT 0 0o0 ?--------- - S_IFDOOR 0 0o0 ?--------- - S_IXOTH 1 0o1 ?--------x - S_IWOTH 2 0o2 ?-------w- - S_IROTH 4 0o4 ?------r-- - S_IRWXO 7 0o7 ?------rwx - S_IXGRP 8 0o10 ?-----x--- - S_IWGRP 16 0o20 ?----w---- - S_IRGRP 32 0o40 ?---r----- - S_IRWXG 56 0o70 ?---rwx--- - S_IEXEC 64 0o100 ?--x------ - S_IXUSR 64 0o100 ?--x------ - S_IWUSR 128 0o200 ?-w------- - S_IWRITE 128 0o200 ?-w------- - S_IREAD 256 0o400 ?r-------- - S_IRUSR 256 0o400 ?r-------- - S_IRWXU 448 0o700 ?rwx------ - S_ISVTX 512 0o1000 ?--------T - S_ISGID 1024 0o2000 ?-----S--- - S_ISUID 2048 0o4000 ?--S------ - S_IFIFO 4096 0o0 p--------- - S_IFCHR 8192 0o0 c--------- - S_IFDIR 16384 0o0 d--------- - S_IFBLK 24576 0o0 b--------- - S_IFREG 32768 0o0 ---------- - S_IFLNK 40960 0o0 l--------- - S_IFSOCK 49152 0o0 s--------- - S_IFWHT 57344 0o0 w--------- + Permissions are set and read using the stat module, see + https://docs.python.org/3/library/stat.html + + Below is a list with the relevant stat attribute names, integer, + octal, and string representations. + + :: + + stat_key stat_mode stat_mode_octal stat_mode_string + -------- --------- --------------- ---------------- + S_IFPORT 0 0o0 ?--------- + S_IFDOOR 0 0o0 ?--------- + S_IXOTH 1 0o1 ?--------x + S_IWOTH 2 0o2 ?-------w- + S_IROTH 4 0o4 ?------r-- + S_IRWXO 7 0o7 ?------rwx + S_IXGRP 8 0o10 ?-----x--- + S_IWGRP 16 0o20 ?----w---- + S_IRGRP 32 0o40 ?---r----- + S_IRWXG 56 0o70 ?---rwx--- + S_IEXEC 64 0o100 ?--x------ + S_IXUSR 64 0o100 ?--x------ + S_IWUSR 128 0o200 ?-w------- + S_IWRITE 128 0o200 ?-w------- + S_IREAD 256 0o400 ?r-------- + S_IRUSR 256 0o400 ?r-------- + S_IRWXU 448 0o700 ?rwx------ + S_ISVTX 512 0o1000 ?--------T + S_ISGID 1024 0o2000 ?-----S--- + S_ISUID 2048 0o4000 ?--S------ + S_IFIFO 4096 0o0 p--------- + S_IFCHR 8192 0o0 c--------- + S_IFDIR 16384 0o0 d--------- + S_IFBLK 24576 0o0 b--------- + S_IFREG 32768 0o0 ---------- + S_IFLNK 40960 0o0 l--------- + S_IFSOCK 49152 0o0 s--------- + S_IFWHT 57344 0o0 w--------- """ import grp @@ -80,7 +85,7 @@ DEFAULT_MODE = stat.S_IRWXU | stat.S_IRGRP # equivalent to '?rwxr-----' def get_group_string(pathname): - """Return the group of pathname in string representation. + """Return the group of ``pathname`` in string representation. Parameters ---------- @@ -91,7 +96,6 @@ def get_group_string(pathname): ------- group_name : str String representation of the group. - """ file_statinfo = os.stat(pathname) groupinfo = grp.getgrgid(file_statinfo.st_gid) @@ -100,7 +104,7 @@ def get_group_string(pathname): def get_owner_string(pathname): - """Return the owner of pathname in string representation. + """Return the owner of ``pathname`` in string representation. Parameters ---------- @@ -111,7 +115,6 @@ def get_owner_string(pathname): ------- owner_name : str String representation of the owner. - """ file_statinfo = os.stat(pathname) ownerinfo = pwd.getpwuid(file_statinfo.st_uid) @@ -120,7 +123,7 @@ def get_owner_string(pathname): def has_permissions(pathname, owner=DEFAULT_OWNER, mode=DEFAULT_MODE, group=DEFAULT_GROUP): - """Return boolean indicating whether pathname has the specified + """Return boolean indicating whether ``pathname`` has the specified owner, permission, and group scheme. Parameters @@ -131,14 +134,13 @@ def has_permissions(pathname, owner=DEFAULT_OWNER, mode=DEFAULT_MODE, group=DEFA String representation of the owner mode : int Integer representation of the permission mode, compatible - with os.stat output + with ``os.stat`` output group : str String representation of the group Returns ------- boolean : bool - """ verify_path(pathname) file_statinfo = os.stat(pathname) @@ -158,7 +160,8 @@ def has_permissions(pathname, owner=DEFAULT_OWNER, mode=DEFAULT_MODE, group=DEFA def set_permissions(pathname, owner=DEFAULT_OWNER, mode=DEFAULT_MODE, group=DEFAULT_GROUP, verbose=True): - """Set mode and group of the file/directory identfied by pathname, if and only if it is owned by owner. + """Set mode and group of the file/directory identfied by + ``pathname``, if and only if it is owned by ``owner``. Parameters ---------- @@ -167,12 +170,12 @@ def set_permissions(pathname, owner=DEFAULT_OWNER, mode=DEFAULT_MODE, group=DEFA owner : str String representation of the owner mode : int - Integer representation of the permission mode, compatible with os.stat output + Integer representation of the permission mode, compatible with + ``os.stat`` output group : str String representation of the group verbose : bool Boolean indicating whether verbose output is requested - """ if verbose: print('\nBefore:') @@ -190,13 +193,13 @@ def set_permissions(pathname, owner=DEFAULT_OWNER, mode=DEFAULT_MODE, group=DEFA def show_permissions(pathname): - """Verbose output showing group, user, and permission information for a directory or file. + """Verbose output showing group, user, and permission information + for a directory or file. Parameters ---------- - pathname: str + pathname : str Directory or file to be inspected - """ verify_path(pathname) file_statinfo = os.stat(pathname) @@ -216,13 +219,13 @@ def show_permissions(pathname): def verify_path(pathname): - """Verify that pathname is either a directory or a file. If not, an error is raised. + """Verify that pathname is either a directory or a file. If not, an + error is raised. Parameters ---------- - pathname: str + pathname : str Directory or file to be inspected - """ if (not os.path.isdir(pathname)) and (not os.path.isfile(pathname)): raise NotImplementedError('{} is not a valid path or filename'.format(pathname)) diff --git a/jwql/preview_image/preview_image.py b/jwql/preview_image/preview_image.py index 34f6521c7..9511d33cc 100755 --- a/jwql/preview_image/preview_image.py +++ b/jwql/preview_image/preview_image.py @@ -5,31 +5,33 @@ This module creates and saves a "preview image" from a fits file that contains a JWST observation. Data from the user-supplied -`extension` of the file are read in, along with the `PIXELDQ` +``extension`` of the file are read in, along with the ``PIXELDQ`` extension if present. For each integration in the exposure, the first group is subtracted from the final group in order to create a difference image. The lower and upper limits to be displayed are -defined as the `clip_percent` and (1. - `clip_percent') percentile -signals. Matplotlib is then used to display a linear- or log-stretched -version of the image, with accompanying colorbar. The image is then -saved. +defined as the ``clip_percent`` and (1. - ``clip_percent``) percentile +signals. ``matplotlib`` is then used to display a linear- or +log-stretched version of the image, with accompanying colorbar. The +image is then saved. Authors: -------- - Bryan Hilbert + - Bryan Hilbert Use: ---- This module can be imported as such: - >>> from jwql.preview_image.preview_image import PreviewImage - im = PreviewImage(my_file, "SCI") - im.clip_percent = 0.01 - im.scaling = 'log' - im.output_format = 'jpg' - im.make_image() + :: + + from jwql.preview_image.preview_image import PreviewImage + im = PreviewImage(my_file, "SCI") + im.clip_percent = 0.01 + im.scaling = 'log' + im.output_format = 'jpg' + im.make_image() """ import os @@ -42,6 +44,7 @@ from jwst.datamodels import dqflags + class PreviewImage(): def __init__(self, filename, extension): @@ -65,43 +68,42 @@ def __init__(self, filename, extension): def difference_image(self, data): """ - Create a difference image from the data. Use last - group minus first group in order to maximize signal - to noise. With 4D input, make a separate difference - image for each integration. + Create a difference image from the data. Use last group minus + first group in order to maximize signal to noise. With 4D + input, make a separate difference image for each integration. - Parameters: + Parameters ---------- data : obj - 4D numpy ndarray array of floats + 4D ``numpy`` ``ndarray`` array of floats - Returns: - -------- + Returns + ------- result : obj - 3D numpy ndarray containing the difference - image(s) from the input exposure + 3D ``numpy`` ``ndarray`` containing the difference image(s) + from the input exposure """ return data[:, -1, :, :] - data[:, 0, :, :] def find_limits(self, data, pixmap, clipperc): """ - Find the minimum and maximum signal levels after - clipping the top and bottom x% of the pixels. + Find the minimum and maximum signal levels after clipping the + top and bottom ``clipperc`` of the pixels. - Parameters: + Parameters ---------- data : obj 2D numpy ndarray of floats pixmap : obj 2D numpy ndarray boolean array of science pixel locations - (True for science pixels, False for non-science pix) + (``True`` for science pixels, ``False`` for non-science + pixels) clipperc : float - Fraction of top and bottom signal levels to clip - (e.g. 0.01 means to clip brightest and dimmest 1% - of pixels) + Fraction of top and bottom signal levels to clip (e.g. 0.01 + means to clip brightest and dimmest 1% of pixels) - Returns: - -------- + Returns + ------- results : tuple Tuple of floats, minimum and maximum signal levels """ @@ -114,24 +116,24 @@ def find_limits(self, data, pixmap, clipperc): def get_data(self, filename, ext): """ - Read in the data from the given file and extension - Also find how many rows/cols of reference pixels are - present. + Read in the data from the given file and extension. Also find + how many rows/cols of reference pixels are present. - Parameters: + Parameters ---------- filename : str Name of fits file containing data ext : str Extension name to be read in - Returns: - -------- + Returns + ------- data : obj Science data from file. A 2-, 3-, or 4D numpy ndarray dq : obj - 2D ndarray boolean map of reference pixels. Science - pixels flagged as True and non-science pixels are False + 2D ``ndarray`` boolean map of reference pixels. Science + pixels flagged as ``True`` and non-science pixels are + ``False`` """ if os.path.isfile(filename): extnames = [] @@ -162,10 +164,10 @@ def make_figure(self, image, integration_number, min_value, max_value, """ Create the matplotlib figure of the image - Parameters: + Parameters ---------- image : obj - 2D numpy ndarray of floats + 2D ``numpy`` ``ndarray`` of floats integration_number : int Integration number within exposure min_value : float @@ -173,10 +175,10 @@ def make_figure(self, image, integration_number, min_value, max_value, max_value : float Maximum value for display scale : str - Image scaling ('log', 'linear') + Image scaling (``log``, ``linear``) - Returns: - -------- + Returns + ------- result : obj Matplotlib Figure object """ @@ -283,10 +285,10 @@ def save_image(image, fname): """ Save an image in the requested output format - Parameters: + Parameters ---------- image : obj - A matplotlib figure object + A ``matplotlib`` figure object fname : str Output filename """ diff --git a/jwql/tests/test_permissions.py b/jwql/tests/test_permissions.py index 59b234841..132e80202 100644 --- a/jwql/tests/test_permissions.py +++ b/jwql/tests/test_permissions.py @@ -1,4 +1,5 @@ -#!/usr/bin/env python +#! /usr/bin/env python + """Tests for the permissions module. Authors @@ -10,11 +11,12 @@ Use --- - These tests can be run via the command line (omit the -s to suppress verbose output to stdout): + These tests can be run via the command line (omit the ``-s`` to + suppress verbose output to ``stdout``): :: - pytest -s test_permissions.py + pytest -s test_permissions.py """ import grp @@ -41,7 +43,6 @@ def test_directory(test_dir=TEST_DIRECTORY): ------- test_dir : str Path to directory used for testing - """ os.mkdir(test_dir) # creates directory with default mode=511 @@ -52,15 +53,16 @@ def test_directory(test_dir=TEST_DIRECTORY): def test_directory_permissions(test_directory): - """Create a directory with the standard permissions ('-rw-r--r--'). + """Create a directory with the standard permissions + ``('-rw-r--r--')``. - Set the default permissions defined in permissions.py. Assert that these were set correctly. + Set the default permissions defined in ``permissions.py``. Assert + that these were set correctly. Parameters ---------- test_directory : str Path of directory used for testing - """ # Get owner and group on the current system.This allows to implement the tests # independently from the user. @@ -85,7 +87,6 @@ def test_file(test_dir=TEST_DIRECTORY): ------- filename : str Path of file used for testing - """ if not os.path.isdir(test_dir): os.mkdir(test_dir) @@ -103,16 +104,17 @@ def test_file(test_dir=TEST_DIRECTORY): # @pytest.mark.xfail def test_file_group(test_file): - """Create a file with the standard permissions ('-rw-r--r--') and default group. + """Create a file with the standard permissions ``('-rw-r--r--')`` + and default group. - Modify the group and set the default permissions defined in permissions.py. - Assert that both group and permissions were set correctly. + Modify the group and set the default permissions defined in + ``permissions.py``. Assert that both group and permissions were + set correctly. Parameters ---------- test_file : str Path of file used for testing - """ # Get owner and group on the current system. owner = get_owner_string(test_file) @@ -131,15 +133,15 @@ def test_file_group(test_file): def test_file_permissions(test_file): - """Create a file with the standard permissions ('-rw-r--r--'). + """Create a file with the standard permissions ``('-rw-r--r--')``. - Set the default permissions defined in permissions.py. Assert that these were set correctly. + Set the default permissions defined in ``permissions.py``. Assert + that these were set correctly. Parameters ---------- test_file : str Path of file used for testing - """ # Get owner and group on the current system. owner = get_owner_string(test_file) diff --git a/jwql/utils/utils.py b/jwql/utils/utils.py index 024b2f7e1..2fc47b2ea 100644 --- a/jwql/utils/utils.py +++ b/jwql/utils/utils.py @@ -1,4 +1,4 @@ -"""Various utility functions for the jwql project. +"""Various utility functions for the ``jwql`` project. Authors ------- @@ -19,7 +19,7 @@ Filename parser modifed from Joe Hunkeler: https://gist.github.com/jhunkeler/f08783ca2da7bfd1f8e9ee1d207da5ff -""" + """ import json import os @@ -29,8 +29,8 @@ def get_config(): - """Return a dictionary that holds the contents of the jwql config - file. + """Return a dictionary that holds the contents of the ``jwql`` + config file. Returns -------