class_docstr: Create dataset sibling at a GitLab site
  
  An existing GitLab project, or a project created via the GitLab web
  interface can be configured as a sibling with the :command:`siblings`
  command. Alternatively, this command can create a GitLab project at any
  location/path a given user has appropriate permissions for. This is
  particularly helpful for recursive sibling creation for subdatasets. API
  access and authentication are implemented via python-gitlab, and all its
  features are supported. A particular GitLab site must be configured in a
  named section of a python-gitlab.cfg file (see
  https://python-gitlab.readthedocs.io/en/stable/cli-usage.html#configuration-file-format
  for details), such as::
  
    [mygit]
    url = https://git.example.com
    api_version = 4
    private_token = abcdefghijklmnopqrst
  
  Subsequently, this site is identified by its name ('mygit' in the example
  above).
  
  (Recursive) sibling creation for all, or a selected subset of subdatasets
  is supported with two different project layouts (see --layout):
  
  "flat"
    All datasets are placed as GitLab projects in the same group. The project name
    of the top-level dataset follows the configured
    datalad.gitlab-SITENAME-project configuration. The project names of
    contained subdatasets extend the configured name with the subdatasets'
    s relative path within the root dataset, with all path separator
    characters replaced by '-'. This path separator is configurable
    (see Configuration).
  "collection"
    A new group is created for the dataset hierarchy, following the
    datalad.gitlab-SITENAME-project configuration. The root dataset is placed
    in a "project" project inside this group, and all nested subdatasets are
    represented inside the group using a "flat" layout. The root datasets
    project name is configurable (see Configuration).
  
  GitLab cannot host dataset content. However, in combination with
  other data sources (and siblings), publishing a dataset to GitLab can
  facilitate distribution and exchange, while still allowing any dataset
  consumer to obtain actual data content from alternative sources.
  
  *Configuration*
  
  Many configuration switches and options for GitLab sibling creation can
  be provided as arguments to the command. However, it is also possible to
  specify a particular setup in a dataset's configuration. This is
  particularly important when managing large collections of datasets.
  Configuration options are:
  
  "datalad.gitlab-default-site"
      Name of the default GitLab site (see --site)
  "datalad.gitlab-SITENAME-siblingname"
      Name of the sibling configured for the local dataset that points
      to the GitLab instance SITENAME (see --name)
  "datalad.gitlab-SITENAME-layout"
      Project layout used at the GitLab instance SITENAME (see --layout)
  "datalad.gitlab-SITENAME-access"
      Access method used for the GitLab instance SITENAME (see --access)
  "datalad.gitlab-SITENAME-project"
      Project "location/path" used for a datasets at GitLab instance
      SITENAME (see --project). Configuring this is useful for deriving
      project paths for subdatasets, relative to superdataset.
      The root-level group ("location") needs to be created beforehand via
      GitLab's web interface.
  "datalad.gitlab-default-projectname"
      The collection layout publishes (sub)datasets as projects
      with a custom name. The default name "project" can be overridden with
      this configuration.
  "datalad.gitlab-default-pathseparator"
      The flat and collection layout represent subdatasets with project names
      that correspond to their path within the superdataset, with the regular path separator replaced
      with a "-": superdataset-subdataset. This configuration can be used to override
      this default separator.
  
  This command can be configured with
  "datalad.create-sibling-ghlike.extra-remote-settings.NETLOC.KEY=VALUE" in
  order to add any local KEY = VALUE configuration to the created sibling in
  the local `.git/config` file. NETLOC is the domain of the Gitlab instance to
  apply the configuration for.
  This leads to a behavior that is equivalent to calling datalad's
  ``siblings('configure', ...)``||``siblings configure`` command with the
  respective KEY-VALUE pair after creating the sibling.
  The configuration, like any other, could be set at user- or system level, so
  users do not need to add this configuration to every sibling created with
  the service at NETLOC themselves.
class_docstr_tok: ["Create","dataset","sibling","at","a","GitLab","site","An","existing","GitLab","project",",","or","a","project","created","via","the","GitLab","web","interface","can","be","configured","as","a","sibling","with","the",":","command",":","`","siblings","`","command",".","Alternatively",",","this","command","can","create","a","GitLab","project","at","any","location\/path","a","given","user","has","appropriate","permissions","for",".","This","is","particularly","helpful","for","recursive","sibling","creation","for","subdatasets",".","API","access","and","authentication","are","implemented","via","python-gitlab",",","and","all","its","features","are","supported",".","A","particular","GitLab","site","must","be","configured","in","a","named","section","of","a","python-gitlab.cfg","file","(","see","https",":","\/\/python-gitlab.readthedocs.io\/en\/stable\/cli-usage.html","#","configuration-file-format","for","details",")",",","such","as",":",":","[","mygit","]","url","=","https",":","\/\/git.example.com","api_version","=","4","private_token","=","abcdefghijklmnopqrst","Subsequently",",","this","site","is","identified","by","its","name","(","'mygit","'","in","the","example","above",")",".","(","Recursive",")","sibling","creation","for","all",",","or","a","selected","subset","of","subdatasets","is","supported","with","two","different","project","layouts","(","see","--","layout",")",":","''","flat","''","All","datasets","are","placed","as","GitLab","projects","in","the","same","group",".","The","project","name","of","the","top-level","dataset","follows","the","configured","datalad.gitlab-SITENAME-project","configuration",".","The","project","names","of","contained","subdatasets","extend","the","configured","name","with","the","subdatasets'","s","relative","path","within","the","root","dataset",",","with","all","path","separator","characters","replaced","by","'-","'",".","This","path","separator","is","configurable","(","see","Configuration",")",".","``","collection","''","A","new","group","is","created","for","the","dataset","hierarchy",",","following","the","datalad.gitlab-SITENAME-project","configuration",".","The","root","dataset","is","placed","in","a","``","project","''","project","inside","this","group",",","and","all","nested","subdatasets","are","represented","inside","the","group","using","a","``","flat","''","layout",".","The","root","datasets","project","name","is","configurable","(","see","Configuration",")",".","GitLab","can","not","host","dataset","content",".","However",",","in","combination","with","other","data","sources","(","and","siblings",")",",","publishing","a","dataset","to","GitLab","can","facilitate","distribution","and","exchange",",","while","still","allowing","any","dataset","consumer","to","obtain","actual","data","content","from","alternative","sources",".","*","Configuration","*","Many","configuration","switches","and","options","for","GitLab","sibling","creation","can","be","provided","as","arguments","to","the","command",".","However",",","it","is","also","possible","to","specify","a","particular","setup","in","a","dataset","'s","configuration",".","This","is","particularly","important","when","managing","large","collections","of","datasets",".","Configuration","options","are",":","''","datalad.gitlab-default-site","''","Name","of","the","default","GitLab","site","(","see","--","site",")","''","datalad.gitlab-SITENAME-siblingname","''","Name","of","the","sibling","configured","for","the","local","dataset","that","points","to","the","GitLab","instance","SITENAME","(","see","--","name",")","''","datalad.gitlab-SITENAME-layout","''","Project","layout","used","at","the","GitLab","instance","SITENAME","(","see","--","layout",")","''","datalad.gitlab-SITENAME-access","''","Access","method","used","for","the","GitLab","instance","SITENAME","(","see","--","access",")","''","datalad.gitlab-SITENAME-project","''","Project","``","location\/path","''","used","for","a","datasets","at","GitLab","instance","SITENAME","(","see","--","project",")",".","Configuring","this","is","useful","for","deriving","project","paths","for","subdatasets",",","relative","to","superdataset",".","The","root-level","group","(","``","location","''",")","needs","to","be","created","beforehand","via","GitLab","'s","web","interface",".","``","datalad.gitlab-default-projectname","''","The","collection","layout","publishes","(","sub",")","datasets","as","projects","with","a","custom","name",".","The","default","name","``","project","''","can","be","overridden","with","this","configuration",".","``","datalad.gitlab-default-pathseparator","''","The","flat","and","collection","layout","represent","subdatasets","with","project","names","that","correspond","to","their","path","within","the","superdataset",",","with","the","regular","path","separator","replaced","with","a","``","-","''",":","superdataset-subdataset",".","This","configuration","can","be","used","to","override","this","default","separator",".","This","command","can","be","configured","with","''","datalad.create-sibling-ghlike.extra-remote-settings.NETLOC.KEY=VALUE","''","in","order","to","add","any","local","KEY","=","VALUE","configuration","to","the","created","sibling","in","the","local","`",".git\/config","`","file",".","NETLOC","is","the","domain","of","the","Gitlab","instance","to","apply","the","configuration","for",".","This","leads","to","a","behavior","that","is","equivalent","to","calling","datalad's","``","siblings","(","'configure","'",",","...",")","``","||","``","siblings","configure","``","command","with","the","respective","KEY-VALUE","pair","after","creating","the","sibling",".","The","configuration",",","like","any","other",",","could","be","set","at","user-","or","system","level",",","so","users","do","not","need","to","add","this","configuration","to","every","sibling","created","with","the","service","at","NETLOC","themselves","."]
code: def __call__(
      path=None,
      *,
      site=None,
      project=None,
      layout=None,
      dataset=None,
      recursive=False,
      recursion_limit=None,
      name=None,
      existing="error",
      access=None,
      publish_depends=None,
      description=None,
      dryrun=False,
      dry_run=False,
  ):
      if dryrun and not dry_run:
          # the old one is used, and not in agreement with the new one
          warnings.warn(
              "datalad-create-sibling-github's `dryrun` option is "
              "deprecated and will be removed in a future release, "
              "use the renamed `dry_run/--dry-run` option instead.",
              DeprecationWarning,
          )
          dry_run = dryrun
      path = (
          resolve_path(ensure_list(path), ds=dataset) if path else None
      )
  
      if project and (recursive or (path and len(path) > 1)):
          raise ValueError(
              "Providing a GitLab project name/location cannot be combined "
              "with recursive operation or multiple paths, as each dataset "
              "needs to be mapped onto its own individual project."
          )
      # what to operate on
      ds = require_dataset(
          dataset,
          check_installed=True,
          purpose="create GitLab sibling(s)",
      )
  
      # cache for objects of gitlab sites (we could face different ones
      # in a single hierarchy, cache them to avoid duplicate initialization
      # while still being able to process each dataset individually
      siteobjs = dict()
  
      # which datasets to process?
      if path is None or ds.pathobj in path:
          for r in _proc_dataset(
              ds,
              ds,
              site,
              project,
              name,
              layout,
              existing,
              access,
              dry_run,
              siteobjs,
              publish_depends,
              description,
          ):
              yield r
      # we need to find a subdataset when recursing, or when there is a path that
      # could point to one, we have to exclude the parent dataset in this test
      # to avoid undesired level-1 recursion into subdatasets
      if any(p != ds.pathobj for p in (path or [])) or recursive:
          # also include any matching subdatasets
          subds = ds.subdatasets(
              path=path,
              # we can only operate on present datasets
              state="present",
              recursive=recursive,
              recursion_limit=recursion_limit,
              contains=None,
              bottomup=False,
              result_xfm="datasets",
              result_renderer="disabled",
              return_type="list",
          )
          if not subds:
              # we didn't find anything to operate on, let the user know
              res_kwargs = {
                  "status": "impossible",
                  "refds": ds.path,
                  "type": "dataset",
                  "logger": lgr,
                  "action": "create_sibling_gitlab",
              }
              if path is not None:
                  for p in path:
                      yield dict(
                          path=p,
                          message=(
                              'No installed dataset found under %s, forgot to "get" it?'
                              % p
                          ),
                          **res_kwargs,
                      )
              else:
                  yield dict(
                      path=ds.path,
                      message=(
                          'No installed subdatasets found underneath %s, forgot to "get" any?'
                          % ds.path
                      ),
                      **res_kwargs,
                  )
          else:
              for sub in subds:
                  for r in _proc_dataset(
                      ds,
                      sub,
                      site,
                      project,
                      name,
                      layout,
                      existing,
                      access,
                      dry_run,
                      siteobjs,
                      publish_depends,
                      description,
                  ):
                      yield r
  
      return
  
imports: import logging
  import warnings
  from datalad.support.exceptions import CapturedException
  from ..distribution.dataset import EnsureDataset, datasetmethod, require_dataset, resolve_path
  from ..distribution.siblings import Siblings
  from ..dochelpers import exc_str
  from ..interface.base import Interface, build_doc, eval_results
  from ..interface.common_opts import publish_depends, recursion_flag, recursion_limit
  from ..local.subdatasets import Subdatasets
  from ..support.constraints import EnsureChoice, EnsureNone, EnsureStr
  from ..support.param import Parameter
  from ..utils import ensure_list
label_desc: Use image node_id 1 for calling the CreateSiblingGitlab obj's underlying member method code with example usage: obj.__call__(path) without return types