class_docstr: Any class that inherits from `Registrable` gains access to a named registry for its
  subclasses. To register them, just decorate them with the classmethod
  `@BaseClass.register(name)`.
  
  After which you can call `BaseClass.list_available()` to get the keys for the
  registered subclasses, and `BaseClass.by_name(name)` to get the corresponding subclass.
  Note that the registry stores the subclasses themselves; not class instances.
  In most cases you would then call `from_params(params)` on the returned subclass.
  
  You can specify a default by setting `BaseClass.default_implementation`.
  If it is set, it will be the first element of `list_available()`.
  
  Note that if you use this class to implement a new `Registrable` abstract class,
  you must ensure that all subclasses of the abstract class are loaded when the module is
  loaded, because the subclasses register themselves in their respective files. You can
  achieve this by having the abstract class and all subclasses in the __init__.py of the
  module in which they reside (as this causes any import of either the abstract class or
  a subclass to load all other subclasses and the abstract class).
class_docstr_tok: ["Any","class","that","inherits","from","`","Registrable","`","gains","access","to","a","named","registry","for","its","subclasses",".","To","register","them",",","just","decorate","them","with","the","classmethod","`","@","BaseClass.register","(","name",")","`",".","After","which","you","can","call","`","BaseClass.list_available","(",")","`","to","get","the","keys","for","the","registered","subclasses",",","and","`","BaseClass.by_name","(","name",")","`","to","get","the","corresponding","subclass",".","Note","that","the","registry","stores","the","subclasses","themselves",";","not","class","instances",".","In","most","cases","you","would","then","call","`","from_params","(","params",")","`","on","the","returned","subclass",".","You","can","specify","a","default","by","setting","`","BaseClass.default_implementation","`",".","If","it","is","set",",","it","will","be","the","first","element","of","`","list_available","(",")","`",".","Note","that","if","you","use","this","class","to","implement","a","new","`","Registrable","`","abstract","class",",","you","must","ensure","that","all","subclasses","of","the","abstract","class","are","loaded","when","the","module","is","loaded",",","because","the","subclasses","register","themselves","in","their","respective","files",".","You","can","achieve","this","by","having","the","abstract","class","and","all","subclasses","in","the","__init__.py","of","the","module","in","which","they","reside","(","as","this","causes","any","import","of","either","the","abstract","class","or","a","subclass","to","load","all","other","subclasses","and","the","abstract","class",")","."]
docstr: Register a class under a particular name.
  
  # Parameters
  
  name : `str`
      The name to register the class under.
  constructor : `str`, optional (default=`None`)
      The name of the method to use on the class to construct the object.  If this is given,
      we will use this method (which must be a `@classmethod`) instead of the default
      constructor.
  exist_ok : `bool`, optional (default=`False`)
      If True, overwrites any existing models registered under `name`. Else,
      throws an error if a model is already registered under `name`.
  
  # Examples
  
  To use this class, you would typically have a base class that inherits from `Registrable`:
  
  ```python
  class Vocabulary(Registrable):
      ...
  ```
  
  Then, if you want to register a subclass, you decorate it like this:
  
  ```python
  @Vocabulary.register("my-vocabulary")
  class MyVocabulary(Vocabulary):
      def __init__(self, param1: int, param2: str):
          ...
  ```
  
  Registering a class like this will let you instantiate a class from a config file, where you
  give `"type": "my-vocabulary"`, and keys corresponding to the parameters of the `__init__`
  method (note that for this to work, those parameters must have type annotations).
  
  If you want to have the instantiation from a config file call a method other than the
  constructor, either because you have several different construction paths that could be
  taken for the same object (as we do in `Vocabulary`) or because you have logic you want to
  happen before you get to the constructor (as we do in `Embedding`), you can register a
  specific `@classmethod` as the constructor to use, like this:
  
  ```python
  @Vocabulary.register("my-vocabulary-from-instances", constructor="from_instances")
  @Vocabulary.register("my-vocabulary-from-files", constructor="from_files")
  class MyVocabulary(Vocabulary):
      def __init__(self, some_params):
          ...
  
      @classmethod
      def from_instances(cls, some_other_params) -> MyVocabulary:
          ...  # construct some_params from instances
          return cls(some_params)
  
      @classmethod
      def from_files(cls, still_other_params) -> MyVocabulary:
          ...  # construct some_params from files
          return cls(some_params)
  ```
docstr_tok: ["Register","a","class","under","a","particular","name",".","#","Parameters","name",":","`","str","`","The","name","to","register","the","class","under",".","constructor",":","`","str","`",",","optional","(","default=","`","None","`",")","The","name","of","the","method","to","use","on","the","class","to","construct","the","object",".","If","this","is","given",",","we","will","use","this","method","(","which","must","be","a","`","@","classmethod","`",")","instead","of","the","default","constructor",".","exist_ok",":","`","bool","`",",","optional","(","default=","`","False","`",")","If","True",",","overwrites","any","existing","models","registered","under","`","name","`",".","Else",",","throws","an","error","if","a","model","is","already","registered","under","`","name","`",".","#","Examples","To","use","this","class",",","you","would","typically","have","a","base","class","that","inherits","from","`","Registrable","`",":","``","`","python","class","Vocabulary","(","Registrable",")",":","...","``","`","Then",",","if","you","want","to","register","a","subclass",",","you","decorate","it","like","this",":","``","`","python","@","Vocabulary.register","(","``","my-vocabulary","''",")","class","MyVocabulary","(","Vocabulary",")",":","def","__init__","(","self",",","param1",":","int",",","param2",":","str",")",":","...","``","`","Registering","a","class","like","this","will","let","you","instantiate","a","class","from","a","config","file",",","where","you","give","`","``","type","''",":","``","my-vocabulary","''","`",",","and","keys","corresponding","to","the","parameters","of","the","`","__init__","`","method","(","note","that","for","this","to","work",",","those","parameters","must","have","type","annotations",")",".","If","you","want","to","have","the","instantiation","from","a","config","file","call","a","method","other","than","the","constructor",",","either","because","you","have","several","different","construction","paths","that","could","be","taken","for","the","same","object","(","as","we","do","in","`","Vocabulary","`",")","or","because","you","have","logic","you","want","to","happen","before","you","get","to","the","constructor","(","as","we","do","in","`","Embedding","`",")",",","you","can","register","a","specific","`","@","classmethod","`","as","the","constructor","to","use",",","like","this",":","``","`","python","@","Vocabulary.register","(","``","my-vocabulary-from-instances","''",",","constructor=","''","from_instances","''",")","@","Vocabulary.register","(","``","my-vocabulary-from-files","''",",","constructor=","''","from_files","''",")","class","MyVocabulary","(","Vocabulary",")",":","def","__init__","(","self",",","some_params",")",":","...","@","classmethod","def","from_instances","(","cls",",","some_other_params",")","-",">","MyVocabulary",":","...","#","construct","some_params","from","instances","return","cls","(","some_params",")","@","classmethod","def","from_files","(","cls",",","still_other_params",")","-",">","MyVocabulary",":","...","#","construct","some_params","from","files","return","cls","(","some_params",")","``","`"]
code: def register(
      cls,
      name: str,
      constructor: Optional[str] = None,
      exist_ok: bool = False,
  ) -> Callable[[Type[_T]], Type[_T]]:
      """
      Register a class under a particular name.
  
      # Parameters
  
      name : `str`
          The name to register the class under.
      constructor : `str`, optional (default=`None`)
          The name of the method to use on the class to construct the object.  If this is given,
          we will use this method (which must be a `@classmethod`) instead of the default
          constructor.
      exist_ok : `bool`, optional (default=`False`)
          If True, overwrites any existing models registered under `name`. Else,
          throws an error if a model is already registered under `name`.
  
      # Examples
  
      To use this class, you would typically have a base class that inherits from `Registrable`:
  
      ```python
      class Vocabulary(Registrable):
          ...
      ```
  
      Then, if you want to register a subclass, you decorate it like this:
  
      ```python
      @Vocabulary.register("my-vocabulary")
      class MyVocabulary(Vocabulary):
          def __init__(self, param1: int, param2: str):
              ...
      ```
  
      Registering a class like this will let you instantiate a class from a config file, where you
      give `"type": "my-vocabulary"`, and keys corresponding to the parameters of the `__init__`
      method (note that for this to work, those parameters must have type annotations).
  
      If you want to have the instantiation from a config file call a method other than the
      constructor, either because you have several different construction paths that could be
      taken for the same object (as we do in `Vocabulary`) or because you have logic you want to
      happen before you get to the constructor (as we do in `Embedding`), you can register a
      specific `@classmethod` as the constructor to use, like this:
  
      ```python
      @Vocabulary.register("my-vocabulary-from-instances", constructor="from_instances")
      @Vocabulary.register("my-vocabulary-from-files", constructor="from_files")
      class MyVocabulary(Vocabulary):
          def __init__(self, some_params):
              ...
  
          @classmethod
          def from_instances(cls, some_other_params) -> MyVocabulary:
              ...  # construct some_params from instances
              return cls(some_params)
  
          @classmethod
          def from_files(cls, still_other_params) -> MyVocabulary:
              ...  # construct some_params from files
              return cls(some_params)
      ```
      """
      registry = Registrable._registry[cls]
  
      def add_subclass_to_registry(subclass: Type[_T]) -> Type[_T]:
          # Add to registry, raise an error if key has already been used.
          if name in registry:
              if exist_ok:
                  message = (
                      f"{name} has already been registered as {registry[name][0].__name__}, but "
                      f"exist_ok=True, so overwriting with {cls.__name__}"
                  )
                  logger.info(message)
              else:
                  message = (
                      f"Cannot register {name} as {cls.__name__}; "
                      f"name already in use for {registry[name][0].__name__}"
                  )
                  raise ConfigurationError(message)
          registry[name] = (subclass, constructor)
          return subclass
  
      return add_subclass_to_registry
  
file_path: allennlp/allennlp/common/registrable.py
imports: import importlib
  import logging
  import inspect
  from collections import defaultdict
  from typing import Callable, ClassVar, DefaultDict, Dict, List, Optional, Tuple, Type, TypeVar, cast, Any
  from allennlp.common.checks import ConfigurationError
  from allennlp.common.from_params import FromParams
label_desc: Use image node_id 1 for calling the Registrable obj's underlying member method code with example usage: obj.register(cls, name, constructor, exist_ok) and returns: add_subclass_to_registry, subclass