Merge pull request #45 from i-VRESSE/google-docstrings

Google docstrings

.flake8

@@ -3,9 +3,14 @@ max-complexity = 6
 inline-quotes = double
 max-line-length = 88
 extend-ignore = E203
-docstring_style=sphinx
 
 ignore =
+  ; flake8-rst-docstrings
+  ; Google Python style is not RST until after processed by Napoleon
+  ; See https://github.com/peterjc/flake8-rst-docstrings/issues/17
+  RST201,RST203,RST301,
+  ; Excess "Returns" in Docstring: + return
+  DAR202,
   ; Found `f` string
   WPS305,
   ; Missing docstring in public module

.pre-commit-config.yaml

@@ -25,6 +25,13 @@ repos:
 
 - repo: local
   hooks:
+  - id: yesqa
+    name: Strip unnecessary `# noqa`s
+    description: Automatically remove unnecessary `# noqa` comments
+    entry: yesqa
+    language: python
+    types: [python]
+
   - id: black
     name: Format with Black
     entry: poetry run black

src/bartender/__main__.py

@@ -27,8 +27,11 @@ def serve() -> None:
 async def make_super_async(email: str) -> None:
     """Async method to grant a user super rights.
 
-    :param email: Email of user
-    :raises ValueError: When user can not be found
+    Args:
+        email: Email of user
+
+    Raises:
+        ValueError: When user can not be found
     """
     session_factory = make_session_factory(make_engine())
     get_user_db_context = contextlib.asynccontextmanager(get_user_db)
@@ -46,15 +49,17 @@ async def make_super_async(email: str) -> None:
 def make_super(email: str) -> None:
     """Grant a user super rights.
 
-    :param email: Email of user
+    Args:
+        email: Email of user
     """
     asyncio.run(make_super_async(email))
 
 
 def build_parser() -> ArgumentParser:
     """Build an argument parser.
 
-    :return: parser
+    Returns:
+        parser
     """
     parser = ArgumentParser(prog="bartender")
     parser.add_argument("--version", action="version", version=version("bartender"))
@@ -73,7 +78,8 @@ def build_parser() -> ArgumentParser:
 def main(argv: list[str] = sys.argv[1:]) -> None:
     """Entrypoint of the application.
 
-    :param argv: Arguments to parse
+    Args:
+        argv: Arguments to parse
     """
     parser = build_parser()
     args = parser.parse_args(argv)

src/bartender/config.py

@@ -1,5 +1,4 @@
-"""
-Parses config file into a list of applications, schedulers and filesystems.
+"""Parses config file into a list of applications, schedulers and filesystems.
 
 Example config:
 
@@ -68,8 +67,8 @@
 class ApplicatonConfiguration(BaseModel):
     """Command to run application.
 
-    `$config` in command string will be replaced
-    with value of ApplicatonConfiguration.config.
+    `$config` in command string will be replaced with value of
+    ApplicatonConfiguration.config.
 
     The config value must be a path relative to the job directory.
 
@@ -87,8 +86,11 @@ class ApplicatonConfiguration(BaseModel):
     def description(self, job_dir: Path) -> JobDescription:
         """Construct job description for this application.
 
-        :param job_dir: In which directory are the input files.
-        :return: A job description.
+        Args:
+            job_dir: In which directory are the input files.
+
+        Returns:
+            A job description.
         """
         command = Template(self.command).substitute(
             config=self.config,
@@ -99,11 +101,11 @@ def description(self, job_dir: Path) -> JobDescription:
 class Config(BaseModel):
     """Bartender configuration.
 
-    The bartender.settings.Settings class is for FastAPI settings.
-    The bartender.config.Config class is for non-FastAPI configuration.
+    The bartender.settings.Settings class is for FastAPI settings. The
+    bartender.config.Config class is for non-FastAPI configuration.
 
-    If config is empty will create a single slot in memory scheduler
-    with a local file system.
+    If config is empty will create a single slot in memory scheduler with a
+    local file system.
 
     """
 
@@ -124,9 +126,14 @@ def applications_non_empty(
     ) -> dict[str, ApplicatonConfiguration]:
         """Validates that applications dict is filled.
 
-        :param v: The given dict.
-        :raises ValueError: When dict is empty.
-        :returns: The given dict.
+        Args:
+            v: The given dict.
+
+        Raises:
+            ValueError: When dict is empty.
+
+        Returns:
+            The given dict.
         """
         if not v:
             raise ValueError("must contain a at least one application")
@@ -140,8 +147,11 @@ def applications_non_empty(
 def build_config(config_filename: Path) -> Config:
     """Build a config instance from a yaml formatted file.
 
-    :param config_filename: File name of configuration file.
-    :return: A config instance.
+    Args:
+        config_filename: File name of configuration file.
+
+    Returns:
+        A config instance.
     """
     raw_config = _load(config_filename)
     return Config(**raw_config)
@@ -155,7 +165,10 @@ def _load(config_filename: Path) -> Any:
 def get_config(request: Request) -> Config:
     """Get config based on current request.
 
-    :param request: The current FastAPI request.
-    :return: The config.
+    Args:
+        request: The current FastAPI request.
+
+    Returns:
+        The config.
     """
     return request.app.state.config

src/bartender/context.py

@@ -24,8 +24,11 @@ class Context:
 def build_context(config: Config) -> Context:
     """Parses a plain configuration dict to a context instance.
 
-    :param config: A plain configuration dict
-    :return: A config instance.
+    Args:
+        config: A plain configuration dict
+
+    Returns:
+        A config instance.
     """
     return Context(
         applications=config.applications,
@@ -38,8 +41,11 @@ def build_context(config: Config) -> Context:
 def get_context(request: Request) -> Context:
     """Get context based on current request.
 
-    :param request: The current FastAPI request.
-    :return: The context.
+    Args:
+        request: The current FastAPI request.
+
+    Returns:
+        The context.
     """
     return request.app.state.context
 
@@ -49,7 +55,8 @@ async def close_context(context: Context) -> None:
 
     A destination might have a remote connection that needs to be cleaned-up.
 
-    :param context: The context.
+    Args:
+        context: The context.
     """
     destinations: dict[str, Destination] = context.destinations
     for destination in destinations.values():

src/bartender/db/base.py

@@ -8,11 +8,9 @@
 
 @as_declarative(metadata=meta)
 class Base:
-    """
-    Base for all models.
+    """Base for all models.
 
-    It has some type definitions to
-    enhance autocompletion.
+    It has some type definitions to enhance autocompletion.
     """
 
     __tablename__: str

src/bartender/db/dao/job_dao.py

@@ -24,15 +24,17 @@ async def create_job(  # noqa: WPS211
         updated_on: Optional[datetime] = None,
         created_on: Optional[datetime] = None,
     ) -> Optional[int]:
-        """
-        Add single job to session.
-
-        :param name: name of a job.
-        :param application: name of application to run job for.
-        :param submitter: User who submitted the job.
-        :param updated_on: Datetime when job was last updated.
-        :param created_on: Datetime when job was created.
-        :return: id of a job.
+        """Add single job to session.
+
+        Args:
+            name: name of a job.
+            application: name of application to run job for.
+            submitter: User who submitted the job.
+            updated_on: Datetime when job was last updated.
+            created_on: Datetime when job was created.
+
+        Returns:
+            id of a job.
         """
         job = Job(
             name=name,
@@ -46,13 +48,15 @@ async def create_job(  # noqa: WPS211
         return job.id
 
     async def get_all_jobs(self, limit: int, offset: int, user: User) -> List[Job]:
-        """
-        Get all job models of user with limit/offset pagination.
+        """Get all job models of user with limit/offset pagination.
+
+        Args:
+            limit: limit of jobs.
+            offset: offset of jobs.
+            user: Which user to get jobs from.
 
-        :param limit: limit of jobs.
-        :param offset: offset of jobs.
-        :param user: Which user to get jobs from.
-        :return: stream of jobs.
+        Returns:
+            stream of jobs.
         """
         raw_jobs = await self.session.execute(
             select(Job)
@@ -64,12 +68,14 @@ async def get_all_jobs(self, limit: int, offset: int, user: User) -> List[Job]:
         return raw_jobs.scalars().fetchall()
 
     async def get_job(self, jobid: int, user: User) -> Job:
-        """
-        Get specific job model.
+        """Get specific job model.
+
+        Args:
+            jobid: name of job instance.
+            user: Which user to get jobs from.
 
-        :param jobid: name of job instance.
-        :param user: Which user to get jobs from.
-        :return: job model.
+        Returns:
+            job model.
         """
         # This is the Asyncrhonous session;
         #  https://docs.sqlalchemy.org/en/14/orm/extensions/asyncio.html#sqlalchemy.ext.asyncio.AsyncSession.refresh
@@ -81,11 +87,11 @@ async def get_job(self, jobid: int, user: User) -> Job:
         return result.scalar_one()
 
     async def update_job_state(self, jobid: int, state: State) -> None:
-        """
-        Update state of a job.
+        """Update state of a job.
 
-        :param jobid: name of job instance.
-        :param state: new state of job instance.
+        Args:
+            jobid: name of job instance.
+            state: new state of job instance.
         """
         job = await self.session.get(Job, jobid)
         if job is None:
@@ -99,12 +105,12 @@ async def update_internal_job_id(
         internal_job_id: str,
         destination: str,
     ) -> None:
-        """
-        Update internal id and destination of a job.
+        """Update internal id and destination of a job.
 
-        :param jobid: name of job instance.
-        :param internal_job_id: new internal job id of job instance.
-        :param destination: To which scheduler/filesystem the job was submitted.
+        Args:
+            jobid: name of job instance.
+            internal_job_id: new internal job id of job instance.
+            destination: To which scheduler/filesystem the job was submitted.
         """
         job = await self.session.get(Job, jobid)
         if job is None:

src/bartender/db/dao/user_dao.py

@@ -18,7 +18,10 @@ async def get_user_db(
 ) -> AsyncGenerator[SQLAlchemyUserDatabase[User, UUID], None]:
     """Factory method for accessing user table.
 
-    :param session: SQLAlchemy session
-    :yield: Database adaptor
+    Args:
+        session: SQLAlchemy session
+
+    Yields:
+        Database adaptor
     """
     yield SQLAlchemyUserDatabase(session, User, OAuthAccount)

src/bartender/db/dependencies.py

@@ -5,11 +5,13 @@
 
 
 async def get_db_session(request: Request) -> AsyncGenerator[AsyncSession, None]:
-    """
-    Create and get database session.
+    """Create and get database session.
+
+    Args:
+        request: current request.
 
-    :param request: current request.
-    :yield: database session.
+    Yields:
+        database session.
     """
     session: AsyncSession = request.app.state.db_session_factory()
 

src/bartender/db/migrations/env.py

@@ -35,13 +35,11 @@
 async def run_migrations_offline() -> None:
     """Run migrations in 'offline' mode.
 
-    This configures the context with just a URL
-    and not an Engine, though an Engine is acceptable
-    here as well.  By skipping the Engine creation
-    we don't even need a DBAPI to be available.
+    This configures the context with just a URL and not an Engine, though an
+    Engine is acceptable here as well.  By skipping the Engine creation we don't
+    even need a DBAPI to be available.
 
-    Calls to context.execute() here emit the given string to the
-    script output.
+    Calls to context.execute() here emit the given string to the script output.
 
     """
     context.configure(
@@ -56,10 +54,10 @@ async def run_migrations_offline() -> None:
 
 
 def do_run_migrations(connection: Connection) -> None:
-    """
-    Run actual sync migrations.
+    """Run actual sync migrations.
 
-    :param connection: connection to the database.
+    Args:
+        connection: connection to the database.
     """
     context.configure(connection=connection, target_metadata=target_metadata)
 
@@ -68,11 +66,10 @@ def do_run_migrations(connection: Connection) -> None:
 
 
 async def run_migrations_online() -> None:
-    """
-    Run migrations in 'online' mode.
+    """Run migrations in 'online' mode.
 
-    In this scenario we need to create an Engine
-    and associate a connection with the context.
+    In this scenario we need to create an Engine and associate a connection with
+    the context.
     """
     connectable = create_async_engine(str(settings.db_url))