Complete the aliases management

Author: aversey

python/aliases.py

@@ -133,6 +133,14 @@ def check(root):
     global ok
     ok = True
     managed = collect_managed(root)
+    for filepath, content in managed.items():
+        if not filepath.exists():
+            print(f"Error: {filepath} should exist.")
+            ok = False
+            continue
+        if filepath.read_text() != content:
+            print(f"Error: {filepath} has wrong content.")
+            ok = False
     ignored = [root / path for path in SOURCES + IGNORED]
 
     def check_file(path):
@@ -142,10 +150,6 @@ def check_file(path):
         if path not in managed:
             print(f"Error: {path} shouldn't exist.")
             ok = False
-            return
-        if path.read_text() != managed[path]:
-            print(f"Error: {path} has wrong content.")
-            ok = False
 
     traverse(root, check_file)
 

python/hopsworks/internal/aliases.py

@@ -27,7 +27,12 @@
 from dataclasses import dataclass, field
 from typing import Dict, Optional
 
-from hopsworks.internal.exceptions import InternalError
+
+class InternalAliasError(Exception):
+    """Internal hopsworks exception related to aliases.
+
+    Ideally, this exception should never happen, as it means misconfiguration of aliases, for example, if a public alias is requested for a method of a class.
+    """
 
 
 @dataclass
@@ -53,15 +58,17 @@ def update(self, other: Alias.InModule):
             self.deprecated |= other.deprecated
             if self.available_until:
                 if self.available_until != other.available_until:
-                    raise InternalError(
+                    raise InternalAliasError(
                         "Deprecated alias is declared available until different releases."
                     )
             else:
                 self.available_until = other.available_until
 
     def __post_init__(self):
         if "." in self.import_name:
-            raise InternalError("Impossible to create alias for not importable symbol.")
+            raise InternalAliasError(
+                "Impossible to create alias for not importable symbol."
+            )
 
     def add(self, *in_modules: InModule):
         for im in in_modules:
@@ -80,98 +87,112 @@ def __new__(cls):
         return Registry
 
     aliases: Dict[str, Alias] = {}
+    modules = {}
 
     @staticmethod
     def get_modules():
-        modules = {}
+        for module, exclude, paths in Registry.modules.values():
+            for name in set(x for x, _ in inspect.getmembers(module)) - exclude:
+                alias = Alias(module.__name__, name)
+                alias.add(*(Alias.InModule(p) for p in paths))
+                Registry.add(alias)
+        res = {}
         for alias in Registry.aliases.values():
             for im in alias.in_modules.values():
                 from_import = alias.from_module, alias.import_name, im
                 parts = im.in_module.split(".")
                 for i in range(1, len(parts)):
-                    modules.setdefault(".".join(parts[:i]), [])
-                modules.setdefault(im.in_module, []).append(from_import)
-        return modules
+                    res.setdefault(".".join(parts[:i]), [])
+                res.setdefault(im.in_module, []).append(from_import)
+        return res
 
     @staticmethod
     def add(*aliases):
         for alias in aliases:
             Registry.aliases.setdefault(alias.get_id(), alias).update(alias)
 
+    @staticmethod
+    def add_module(module, exclude, paths):
+        Registry.modules[module.__name__] = module, exclude, paths
+
 
-def public(*paths: str, as_alias: Optional[str] = None):
+def public(
+    *paths: str,
+    as_alias: Optional[str] = None,
+    deprecated: bool = False,
+    available_until: Optional[str] = None,
+):
     """Make a function or class publically available.
 
     If you want to publish a constant, use `publish`.
-    Note that it is impossible to create an alias for a variable, i.e., it is impossible to make a change of a variable in one module to propogate to another variable in another module.
 
     # Arguments
         paths: the import paths under which the entity is publically avilable; effectively results in generation of aliases in all of the paths for the entity.
         as_alias: make the alias of the specified name.
+        deprecated: make the alias deprected; use of the entity outside hopsworks will print a warning, saying that it is going to be removed from the public API in one of the future releases. See `deprecated` decorator for the implementation of construction of the deprecated objects.
+        available_until: the first hopsworks release in which the entity will become unavailable, defaults to `None`; if the release is known, it is reoprted to the external user in the warning and `deprected` becomes set up.
     """
 
+    if available_until:
+        deprecated = True
+
     def decorator(symbol):
         if not hasattr(symbol, "__qualname__"):
-            raise InternalError("The symbol should be importable to be public.")
+            raise InternalAliasError("The symbol should be importable to be public.")
         alias = Alias(symbol.__module__, symbol.__qualname__)
-        alias.add(*(Alias.InModule(p, as_alias) for p in paths))
+        alias.add(
+            *(Alias.InModule(p, as_alias, deprecated, available_until) for p in paths)
+        )
         Registry.add(alias)
         return symbol
 
     return decorator
 
 
-class Publisher:
-    """Publish all of the names defined inside this context.
+def publish(*paths: str):
+    """Publish all of the names defined in this module after this call.
 
     Since `public` decorator works only for classes and functions, this context should be used for public constants.
     It is also useful for bulk publishing.
     Note that it is impossible to create an alias for a variable, i.e., it is impossible to make a change of a variable in one module to propogate to another variable in another module.
 
+    In case you need to publish something from the begining of a module, use `Publisher`.
+
+    If you need to deprecate an alias, use `public` instead.
+
     # Arguments
         paths: the import paths under which the names declared in this context will be publically available; effectively results in generation of aliases in all of the paths for all the names declared in the context.
     """
 
-    def __init__(self, *paths: str):
-        self.paths = set(paths)
+    caller = inspect.getmodule(inspect.stack()[1][0])
+    exclude = set(x for x, _ in inspect.getmembers(caller))
+    Registry.add_module(caller, exclude, paths)
 
-    def __enter__(self):
-        caller = inspect.getmodule(inspect.stack()[1][0])
-        self.exclude = set(x for x, _ in inspect.getmembers(caller))
-
-    def __exit__(self, _exc_type, _exc_value, _traceback):
-        caller = inspect.getmodule(inspect.stack()[1][0])
-        for name in set(x for x, _ in inspect.getmembers(caller)) - self.exclude:
-            alias = Alias(caller.__name__, name)
-            alias.add(*(Alias.InModule(p) for p in self.paths))
-            Registry.add(alias)
 
+class Publisher:
+    """Publish all of the names defined inside this context.
 
-def deprecated_public(
-    *paths: str,
-    available_until: Optional[str] = None,
-    as_alias: Optional[str] = None,
-):
-    """Make public aliases as a deprecated versions of a class or a function.
+    This class is intended for bulk publishing of entitities which are to be declared in the begining of a module, so that publish is not usable; in other cases, use publish instead.
+    Note that it is impossible to create an alias for a variable, i.e., it is impossible to make a change of a variable in one module to propogate to another variable in another module.
 
-    Use of the entity outside hopsworks will print a warning, saying that it is going to be removed from the public API in one of the future releases.
-    See `deprecated` decorator for the implementation of construction of the deprecated objects.
+    If you need to deprecate an alias, use `public` instead.
 
     # Arguments
-        paths: the import paths under which the entity is publically avilable; effectively results in generation of deprecated aliases in all of the paths for the entity.
-        available_until: the first hopsworks release in which the entity will become unavailable, defaults to `None`; if the release is known, it is reoprted to the external user in the warning.
-        as_alias: make the alias of the specified name.
+        paths: the import paths under which the names declared in this context will be publically available; effectively results in generation of aliases in all of the paths for all the names declared in the context.
     """
 
-    def decorator(symbol):
-        if not hasattr(symbol, "__qualname__"):
-            raise InternalError("The symbol should be importable to be public.")
-        alias = Alias(symbol.__module__, symbol.__qualname__)
-        alias.add(*(Alias.InModule(p, as_alias, True, available_until) for p in paths))
-        Registry.add(alias)
-        return symbol
+    def __init__(self, *paths: str):
+        self.paths = set(paths)
+        self.caller = inspect.getmodule(inspect.stack()[1][0])
 
-    return decorator
+    def __enter__(self):
+        self.exclude = set(x for x, _ in inspect.getmembers(self.caller))
+
+    def __exit__(self, _exc_type, _exc_value, _traceback):
+        for name in set(x for x, _ in inspect.getmembers(self.caller)) - self.exclude:
+            alias = Alias(self.caller.__name__, name)
+            alias.add(*(Alias.InModule(p) for p in self.paths))
+            Registry.add(alias)
 
 
 class DeprecatedCallWarning(Warning):
@@ -212,6 +233,8 @@ def deprecated_f(*args, **kwargs):
 
             return deprecated_f
         else:
-            raise InternalError("Deprecation of something else than class or function.")
+            raise InternalAliasError(
+                "Deprecation of something else than class or function."
+            )
 
     return deprecate