Added account job attribute to use for accounting/billing.

Deprecate the `project` attribute and re-direct it to `account`.

Author: hategan

QuickStart.md

@@ -58,7 +58,7 @@ def make_job():
     spec.arguments = ['HELLO WORLD!']
 
     # set project name if no default is specified
-    # spec.attributes.project_name = <PROJECT_NAME>
+    # spec.attributes.account = <PROJECT_NAME>
 
     # set queue if no default is specified
     # spec.attributes.queue_name = <QUEUE_NAME>

docs/_static/extras.js

@@ -86,8 +86,8 @@ function detectAll(selectorType) {
             else if (text == "queue_name") {
                 $(this).text("QUEUE_NAME");
             }
-            else if (text == "project_name") {
-                $(this).text("PROJECT_NAME");
+            else if (text == "account") {
+                $(this).text("ACCOUNT");
             }
         }
         if (text == '_get_executor_instance') {

docs/user_guide.rst

@@ -335,7 +335,7 @@ and an instance of the
     :lines: 10-18,21-22
 
 where `QUEUE_NAME` is the LRM queue where the job should be sent and
-`PROJECT_NAME` is a project/account that may need to be specified for
+`ACCOUNT` is a project/account that may need to be specified for
 accounting purposes. These values generally depend on the system and allocation
 being used.
 

src/psij/executors/batch/cobalt/cobalt.mustache

@@ -25,9 +25,9 @@
     {{#reservation_id}}
 #COBALT --queue={{.}}
     {{/reservation_id}}
-    {{#project_name}}
+    {{#account}}
 #COBALT --project={{.}}
-    {{/project_name}}
+    {{/account}}
 {{/job.spec.attributes}}
 
 {{#custom_attributes}}

src/psij/executors/batch/lsf/lsf.mustache

@@ -44,10 +44,10 @@
 #BSUB -q "{{.}}"
     {{/queue_name}}
 
-    {{#project_name}}
+    {{#account}}
 #BSUB -G "{{.}}"
 #BSUB -P "{{.}}"
-    {{/project_name}}
+    {{/account}}
 
     {{#reservation_id}}
 #BSUB -U "{{.}}"

src/psij/executors/batch/pbs/pbs_classic.mustache

@@ -21,9 +21,9 @@
 {{/formatted_job_duration}}
 
 {{#job.spec.attributes}}
-    {{#project_name}}
-#PBS -P {{.}}
-    {{/project_name}}
+    {{#account}}
+#PBS -A {{.}}
+    {{/account}}
     {{#queue_name}}
 #PBS -q {{.}}
     {{/queue_name}}

src/psij/executors/batch/pbs/pbspro.mustache

@@ -24,9 +24,9 @@
 {{/formatted_job_duration}}
 
 {{#job.spec.attributes}}
-    {{#project_name}}
-#PBS -P {{.}}
-    {{/project_name}}
+    {{#account}}
+#PBS -A {{.}}
+    {{/account}}
     {{#queue_name}}
 #PBS -q {{.}}
     {{/queue_name}}

src/psij/executors/batch/slurm/slurm.mustache

@@ -48,9 +48,9 @@
 #SBATCH --partition="{{.}}"
     {{/queue_name}}
 
-    {{#project_name}}
+    {{#account}}
 #SBATCH --account="{{.}}"
-    {{/project_name}}
+    {{/account}}
 
     {{#reservation_id}}
 #SBATCH --reservation="{{.}}"

src/psij/job_attributes.py

@@ -1,10 +1,14 @@
+import logging
 import re
 from datetime import timedelta
 from typing import Optional, Dict
 
 from typeguard import check_argument_types
 
 
+logger = logging.getLogger(__name__)
+
+
 _WALLTIME_FMT_ERROR = 'Unknown walltime format: %s. Accepted formats are hh:mm:ss, ' \
                       'hh:mm, mm, or n\\s*[h|m|s].'
 
@@ -13,17 +17,19 @@ class JobAttributes(object):
     """A class containing ancillary job information that describes how a job is to be run."""
 
     def __init__(self, duration: timedelta = timedelta(minutes=10),
-                 queue_name: Optional[str] = None, project_name: Optional[str] = None,
+                 queue_name: Optional[str] = None, account: Optional[str] = None,
                  reservation_id: Optional[str] = None,
-                 custom_attributes: Optional[Dict[str, object]] = None) -> None:
+                 custom_attributes: Optional[Dict[str, object]] = None,
+                 project_name: Optional[str] = None) -> None:
         """
         :param duration: Specifies the duration (walltime) of the job. A job whose execution
             exceeds its walltime can be terminated forcefully.
         :param queue_name: If a backend supports multiple queues, this parameter can be used to
             instruct the backend to send this job to a particular queue.
-        :param project_name: If a backend supports multiple projects for billing purposes, setting
-            this attribute instructs the backend to bill the indicated project for the resources
-            consumed by this job.
+        :param account: An account to use for billing purposes. Please note that the executor
+            implementation (or batch scheduler) may use a different term for the option used for
+            accounting/billing purposes, such as `project`. However, scheduler must map this
+            attribute to the accounting/billing option in the underlying execution mechanism.
         :param reservation_id: Allows specifying an advanced reservation ID. Advanced reservations
             enable the pre-allocation of a set of resources/compute nodes for a certain duration
             such that jobs can be run immediately, without waiting in the queue for resources to
@@ -39,11 +45,13 @@ def __init__(self, duration: timedelta = timedelta(minutes=10),
             `pbs.c`, `lsf.core_isolation`) and translate them into the corresponding batch
             scheduler directives (e.g., `#SLURM --constraint=...`, `#PBS -c ...`,
             `#BSUB -core_isolation ...`).
+        :param project_name: Deprecated. Please use the `account` attribute.
 
         All constructor parameters are accessible as properties.
         """
         assert check_argument_types()
 
+        self.account = account
         self.duration = duration
         self.queue_name = queue_name
         self.project_name = project_name
@@ -86,8 +94,8 @@ def custom_attributes(self, attrs: Optional[Dict[str, object]]) -> None:
 
     def __repr__(self) -> str:
         """Returns a string representation of this object."""
-        return 'JobAttributes(duration={}, queue_name={}, project_name={}, reservation_id={}, ' \
-               'custom_attributes={})'.format(self.duration, self.queue_name, self.project_name,
+        return 'JobAttributes(duration={}, queue_name={}, account={}, reservation_id={}, ' \
+               'custom_attributes={})'.format(self.duration, self.queue_name, self.account,
                                               self.reservation_id, self._custom_attributes)
 
     def __eq__(self, o: object) -> bool:
@@ -99,7 +107,7 @@ def __eq__(self, o: object) -> bool:
         if not isinstance(o, JobAttributes):
             return False
 
-        for prop_name in ['duration', 'queue_name', 'project_name', 'reservation_id',
+        for prop_name in ['duration', 'queue_name', 'account', 'reservation_id',
                           'custom_attributes']:
             if getattr(self, prop_name) != getattr(o, prop_name):
                 return False
@@ -150,3 +158,14 @@ def parse_walltime(walltime: str) -> timedelta:
             elif unit == 's':
                 return timedelta(seconds=val)
         raise ValueError(_WALLTIME_FMT_ERROR % walltime)
+
+    @property
+    def project_name(self) -> Optional[str]:
+        """Deprecated. Please use the `account` attribute."""
+        return self.account
+
+    @project_name.setter
+    def project_name(self, project_name: Optional[str]) -> None:
+        logger.warning('The "project_name" attribute is deprecated. Please use the "account" '
+                       'attribute instead.')
+        self.account = project_name

testing.conf

@@ -119,7 +119,7 @@ queue_name =
 # If you need a project/account for billing purposes, enter it here.
 #
 
-project_name =
+account =