Rename model description to externals description.

Testing:
  unit tests - pass
  cesm - manual testing of checkout and status - ok.
  clm - manual testing of checkout and status - ok.

checkout_externals.py

@@ -27,7 +27,7 @@
     print(70 * '*')
     sys.exit(1)
 
-from manic import read_model_description_file, create_model_description
+from manic import read_externals_description_file, create_externals_description
 from manic import SourceTree
 from manic import check_safe_to_update_repos
 from manic import printlog, PPRINTER
@@ -43,13 +43,13 @@ def commandline_arguments():
     """
     description = '''
 %(prog)s manages checking out CESM externals from revision control
-based on a model description file. By default only the required
+based on a externals description file. By default only the required
 components of the model are checkout out.
 
 NOTE: %(prog)s *MUST* be run from the root of the source tree.
 
 Running %(prog)s without the '--status' option will always attempt to
-synchronize the working copy with the model description.
+synchronize the working copy with the externals description.
 '''
 
     epilog = '''
@@ -76,7 +76,7 @@ def commandline_arguments():
       $ ./checkout_cesm/%(prog)s
 
   * To update all required components to the current values in the
-    model description file, re-run %(prog)s:
+    externals description file, re-run %(prog)s:
 
       $ cd ${SRC_ROOT}
       $ ./checkout_cesm/%(prog)s
@@ -107,12 +107,12 @@ def commandline_arguments():
 
     where:
       * column one indicates the status of the repository in relation
-        to the model description file.
+        to the externals description file.
       * column two indicates whether the working copy has modified files.
       * column three shows how the repository is managed, optional or required
 
     Colunm one will be one of these values:
-      * m : modified : repository is modefied compared to the model description
+      * m : modified : repository is modefied compared to the externals description
       * e : empty : directory does not exist - %(prog)s has not been run
       * ? : unknown : directory exists but .git or .svn directories are missing
 
@@ -132,7 +132,7 @@ def commandline_arguments():
 
 # Model description file:
 
-  The model description contains a list of the model components that
+  The externals description contains a list of the model components that
   are used and their version control locations. Each component has:
 
   * name (string) : component name, e.g. cime, cism, clm, cam, etc.
@@ -162,7 +162,7 @@ def commandline_arguments():
 
   * externals (string) : relative path to the external model
     description file that should also be used. It is *relative* to the
-    component local_path. For example, the CESM model description will
+    component local_path. For example, the CESM externals description will
     load clm. CLM has additional externals that must be downloaded to
     be complete. Those additional externals are managed from the clm
     source root by the file pointed to by 'externals'.
@@ -177,7 +177,7 @@ def commandline_arguments():
     # user options
     #
     parser.add_argument('-m', '--model', nargs='?', default='CESM.cfg',
-                        help='The model description filename. '
+                        help='The externals description filename. '
                         'Default: %(default)s.')
 
     parser.add_argument('-o', '--optional', action='store_true', default=False,
@@ -232,8 +232,8 @@ def _main(args):
         load_all = True
 
     root_dir = os.path.abspath('.')
-    model_data = read_model_description_file(root_dir, args.model)
-    model = create_model_description(model_data)
+    model_data = read_externals_description_file(root_dir, args.model)
+    model = create_externals_description(model_data)
     if args.debug:
         PPRINTER.pprint(model)
 

manic/__init__.py

@@ -3,13 +3,13 @@
 
 from manic.utils import printlog, log_process_output, fatal_error
 from manic.globals import PPRINTER
-from manic.model_description import read_model_description_file
-from manic.model_description import create_model_description
+from manic.externals_description import read_externals_description_file
+from manic.externals_description import create_externals_description
 from manic.sourcetree import SourceTree
 from manic.externalstatus import check_safe_to_update_repos
 
 __all__ = ['PPRINTER',
            'printlog', 'log_process_output', 'fatal_error',
-           'read_model_description_file', 'create_model_description',
+           'read_externals_description_file', 'create_externals_description',
            'SourceTree',
            ]

manic/model_description.py → manic/externals_description.py

@@ -7,7 +7,7 @@
 converts it into a standard interface that is used by the rest of the
 system.
 
-To maintain backward compatibility, model description files should
+To maintain backward compatibility, externals description files should
 follow semantic versioning rules, http://semver.org/
 
 
@@ -49,56 +49,56 @@ def config_string_cleaner(text):
 VERSION_ITEM = 'version'
 
 
-def read_model_description_file(root_dir, file_name):
-    """Given a file name containing a model description, determine the
+def read_externals_description_file(root_dir, file_name):
+    """Given a file name containing a externals description, determine the
     format and read it into it's internal representation.
 
     """
     root_dir = os.path.abspath(root_dir)
     msg = 'In directory : {0}'.format(root_dir)
     logging.info(msg)
-    printlog('Processing model description file : {0}'.format(file_name))
+    printlog('Processing externals description file : {0}'.format(file_name))
 
     file_path = os.path.join(root_dir, file_name)
     if not os.path.exists(file_name):
         msg = ('ERROR: Model description file, "{0}", does not '
                'exist at {1}'.format(file_name, file_path))
         fatal_error(msg)
 
-    model_description = None
+    externals_description = None
     try:
         config = config_parser()
         config.read(file_path)
-        model_description = config
+        externals_description = config
     except ConfigParser.MissingSectionHeaderError:
         # not a cfg file
         pass
 
-    if model_description is None:
+    if externals_description is None:
         msg = 'Unknown file format!'
         fatal_error(msg)
 
-    return model_description
+    return externals_description
 
 
-def create_model_description(model_data, model_format='cfg'):
-    """Create the a model description object from the provided data
+def create_externals_description(model_data, model_format='cfg'):
+    """Create the a externals description object from the provided data
     """
-    model_description = None
+    externals_description = None
     if model_format == 'dict':
-        model_description = ModelDescriptionDict(model_data, )
+        externals_description = ExternalsDescriptionDict(model_data, )
     elif model_format == 'cfg':
         major, _, _ = get_cfg_schema_version(model_data)
         if major == 1:
-            model_description = ModelDescriptionConfigV1(model_data)
+            externals_description = ExternalsDescriptionConfigV1(model_data)
         else:
             msg = ('Externals description file has unsupported schema '
                    'version "{0}".'.format(major))
             fatal_error(msg)
     else:
         msg = 'Unknown model data format "{0}"'.format(model_format)
         fatal_error(msg)
-    return model_description
+    return externals_description
 
 
 def get_cfg_schema_version(model_cfg):
@@ -132,14 +132,14 @@ def get_cfg_schema_version(model_cfg):
     return major, minor, patch
 
 
-class ModelDescription(dict):
-    """Base model description class that is independent of the user input
+class ExternalsDescription(dict):
+    """Base externals description class that is independent of the user input
     format. Different input formats can all be converted to this
     representation to provide a consistent represtentation for the
     rest of the objects in the system.
 
     """
-    # keywords defining the interface into the model description data
+    # keywords defining the interface into the externals description data
     EXTERNALS = 'externals'
     BRANCH = 'branch'
     REPO = 'repo'
@@ -222,7 +222,7 @@ def _check_data(self):
     def _check_optional(self):
         """Some fields like externals, repo:tag repo:branch are
         (conditionally) optional. We don't want the user to be
-        required to enter them in every model description file, but
+        required to enter them in every externals description file, but
         still want to validate the input. Check conditions and add
         default values if appropriate.
 
@@ -241,7 +241,7 @@ def _check_optional(self):
                 self[field][self.REPO][self.REPO_URL] = EMPTY_STR
 
     def _validate(self):
-        """Validate that the parsed model description contains all necessary
+        """Validate that the parsed externals description contains all necessary
         fields.
 
         """
@@ -285,22 +285,22 @@ def validate_data_struct(schema, data):
                 fatal_error(msg)
 
 
-class ModelDescriptionDict(ModelDescription):
-    """Create a model description object from a dictionary using the API
+class ExternalsDescriptionDict(ExternalsDescription):
+    """Create a externals description object from a dictionary using the API
     representations. Primarily used to simplify creating model
     description files for unit testing.
 
     """
     def __init__(self, model_data):
-        """Parse a native dictionary into a model description.
+        """Parse a native dictionary into a externals description.
         """
-        ModelDescription.__init__(self)
+        ExternalsDescription.__init__(self)
         self.update(model_data)
         self._check_user_input()
 
 
-class ModelDescriptionConfigV1(ModelDescription):
-    """Create a model description object from a config_parser object,
+class ExternalsDescriptionConfigV1(ExternalsDescription):
+    """Create a externals description object from a config_parser object,
     schema version 1.
 
     """
@@ -309,7 +309,7 @@ def __init__(self, model_data):
         construct the source objects
 
         """
-        ModelDescription.__init__(self)
+        ExternalsDescription.__init__(self)
         self._remove_metadata(model_data)
         self._parse_cfg(model_data)
         self._check_user_input()
@@ -324,7 +324,7 @@ def _remove_metadata(model_data):
         model_data.remove_section(DESCRIPTION_SECTION)
 
     def _parse_cfg(self, cfg_data):
-        """Parse a config_parser object into a model description.
+        """Parse a config_parser object into a externals description.
         """
         def list_to_dict(input_list, convert_to_lower_case=True):
             """Convert a list of key-value pairs into a dictionary.

manic/externalstatus.py

@@ -12,7 +12,7 @@ class ExternalStatus(object):
 
     There are two states of concern:
 
-    * If the repository is in-sync with the model description file.
+    * If the repository is in-sync with the externals description file.
 
     * If the repostiory working copy is clean and there are no pending
     transactions (e.g. add, remove, rename, untracked files).
@@ -105,7 +105,7 @@ def check_safe_to_update_repos(tree_status, debug):
     the model in an inconsistent state.
 
     Note: if there is an update to do, the repositories will by
-    definiation be out of synce with the model description, so we
+    definiation be out of synce with the externals description, so we
     can't use that as criteria for updating.
 
     """

manic/repository.py

@@ -1,7 +1,7 @@
 """Base class representation of a repository
 """
 
-from .model_description import ModelDescription
+from .externals_description import ExternalsDescription
 from .utils import fatal_error
 from .globals import EMPTY_STR
 
@@ -13,13 +13,13 @@ class Repository(object):
 
     def __init__(self, component_name, repo):
         """
-        Parse repo model description
+        Parse repo externals description
         """
         self._name = component_name
-        self._protocol = repo[ModelDescription.PROTOCOL]
-        self._tag = repo[ModelDescription.TAG]
-        self._branch = repo[ModelDescription.BRANCH]
-        self._url = repo[ModelDescription.REPO_URL]
+        self._protocol = repo[ExternalsDescription.PROTOCOL]
+        self._tag = repo[ExternalsDescription.TAG]
+        self._branch = repo[ExternalsDescription.BRANCH]
+        self._url = repo[ExternalsDescription.REPO_URL]
 
         if self._url is EMPTY_STR:
             fatal_error('repo must have a URL')

manic/repository_factory.py

@@ -1,6 +1,6 @@
 from .repository_git import GitRepository
 from .repository_svn import SvnRepository
-from .model_description import ModelDescription
+from .externals_description import ExternalsDescription
 from .utils import fatal_error
 
 
@@ -9,7 +9,7 @@ def create_repository(component_name, repo_info):
     create the appropriate object.
 
     """
-    protocol = repo_info[ModelDescription.PROTOCOL].lower()
+    protocol = repo_info[ExternalsDescription.PROTOCOL].lower()
     if protocol == 'git':
         repo = GitRepository(component_name, repo_info)
     elif protocol == 'svn':

manic/repository_svn.py

@@ -49,7 +49,7 @@ def checkout(self, base_dir_path, repo_dir_name):
         """Checkout or update the working copy
 
         If the repo destination directory exists, switch the sandbox to
-        match the model description.
+        match the externals description.
 
         If the repo destination directory does not exist, checkout the
         correct branch or tag.