Skip to content

Reference

scope(*args, **kwargs)

Bases: _HyperParameter

A thread-safe hyperparameter context scope

Examples:

create new scope

>>> ps = scope(a="a", b="b")           # create from call arguments
>>> ps = scope(**{"a": "a", "b": "b"}) # create from a dict

read parameters from scope

>>> ps.a() # read parameter
'a'
>>> ps.c("c")  # read parameter with default value if missing
'c'
>>> ps.c | "c" # another way for reading missing parameters
'c'

scope as a context scope

>>> with scope(**{"a": "a"}) as ps:
...     print(ps.a())
a

read parameter from scope in a function

>>> def foo():
...    with scope() as ps:
...        return ps.a()
>>> with scope(**{"a": "a", "b": "b"}) as ps:
...     foo() # foo should get scope using a with statement
'a'

modify parameters in nested scopes

>>> with scope.empty(**{'a': 1, 'b': 2}) as ps:
...     _repr_dict(ps.storage().storage())
...     with scope(**{'b': 3}) as ps:
...         _repr_dict(ps.storage().storage())
...     with scope() as ps:
...         _repr_dict(ps.storage().storage())
[('a', 1), ('b', 2)]
[('a', 1), ('b', 3)]
[('a', 1), ('b', 2)]

use object-style parameter key in scope

>>> with scope(**{"a.b.c": [1,2]}) as ps:
...     ps.a.b.c()
[1, 2]

access parameter with scope

>>> with scope(x=1):
...     scope.x(2) # read parameter
...     scope.y(2) # read a missing parameter with default value
...     scope.y | 2
...     scope.z = 3
...     scope.z | 0
1
2
2
3

convert scope to dict:

>>> ps = scope.empty(a=1, b=2)
>>> _repr_dict(dict(ps))
[('a', 1), ('b', 2)]
Source code in hyperparameter/api.py 
508
509
510
511
512
513
514
def __init__(self, *args: str, **kwargs: Any) -> None:
    super().__init__()
    self.update(kwargs)
    for line in args:
        if "=" in line:
            k, v = line.split("=", 1)
            self.put(k, v)

__enter__()

enter a scope context

Examples:

>>> with scope():
...     scope.p = "origin"
...     with scope(**{"p": "origin"}) as ps:
...         ps.storage().storage()      # outer scope
...         with scope() as ps:   # unmodified scope
...             ps.storage().storage()  # inner scope
...         with scope(**{"p": "modified"}) as ps: # modified scope
...             ps.storage().storage()  # inner scope with modified params
...         _ = scope(**{"p": "modified"}) # not used in with ctx
...         with scope() as ps:   # unmodified scope
...             ps.storage().storage()  # inner scope
{'p': 'origin'}
{'p': 'origin'}
{'p': 'modified'}
{'p': 'origin'}
Source code in hyperparameter/api.py 
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
def __enter__(self) -> "scope":
    """enter a `scope` context

    Examples
    --------
    >>> with scope():
    ...     scope.p = "origin"
    ...     with scope(**{"p": "origin"}) as ps:
    ...         ps.storage().storage()      # outer scope
    ...         with scope() as ps:   # unmodified scope
    ...             ps.storage().storage()  # inner scope
    ...         with scope(**{"p": "modified"}) as ps: # modified scope
    ...             ps.storage().storage()  # inner scope with modified params
    ...         _ = scope(**{"p": "modified"}) # not used in with ctx
    ...         with scope() as ps:   # unmodified scope
    ...             ps.storage().storage()  # inner scope
    {'p': 'origin'}
    {'p': 'origin'}
    {'p': 'modified'}
    {'p': 'origin'}
    """

    self._storage.enter()
    return self

current() staticmethod

get current scope

Examples:

>>> with scope(a=1) as ps:
...     scope.current().a("empty") # read `a` from current `scope`
'1'

>>> with scope() as ps1:
...     with scope(a=1) as ps2:
...         scope.current().a = 2  # set parameter `a` = 2
...         scope.a("empty")       # read `a` in `ps2`
...     scope.a("empty")           # read `a` in `ps1`, where `a` is not set
'2'
'empty'
Source code in hyperparameter/api.py 
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
@staticmethod
def current() -> "scope":
    """get current `scope`

    Examples
    --------
    >>> with scope(a=1) as ps:
    ...     scope.current().a("empty") # read `a` from current `scope`
    '1'

    >>> with scope() as ps1:
    ...     with scope(a=1) as ps2:
    ...         scope.current().a = 2  # set parameter `a` = 2
    ...         scope.a("empty")       # read `a` in `ps2`
    ...     scope.a("empty")           # read `a` in `ps1`, where `a` is not set
    '2'
    'empty'
    """
    retval = scope()
    retval._storage = TLSKVStorage.current()
    return retval

empty(*args, **kwargs) staticmethod

create an empty scope.

Examples:

>>> with scope(a="not empty") as ps: # start a new scope `a` = 'not empty'
...     scope.a("empty")             # read parameter `a`
...     with scope.empty() as ps2:   # parameter `a` is cleared in ps2
...         scope.a("empty")         # read parameter `a` = 'empty'
'not empty'
'empty'
Source code in hyperparameter/api.py 
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
@staticmethod
def empty(*args: str, **kwargs: Any) -> "scope":
    """create an empty `scope`.

    Examples
    --------
    >>> with scope(a="not empty") as ps: # start a new scope `a` = 'not empty'
    ...     scope.a("empty")             # read parameter `a`
    ...     with scope.empty() as ps2:   # parameter `a` is cleared in ps2
    ...         scope.a("empty")         # read parameter `a` = 'empty'
    'not empty'
    'empty'
    """
    retval = scope().clear().update(kwargs)
    for line in args:
        if "=" in line:
            k, v = line.split("=", 1)
            retval.put(k, v)
    return retval

init(params=None) staticmethod

init scope for a new thread.

Source code in hyperparameter/api.py 
594
595
596
597
598
599
@staticmethod
def init(params: Optional[Dict[str, Any]] = None) -> None:
    """init scope for a new thread."""
    if params is None:
        params = {}
    scope(**params).__enter__()

param(name_or_func) 

param(func: Callable) -> Callable

param(name: str) -> Callable[[Callable], Callable]

Convert keyword arguments into hyperparameters

Examples:

>>> @param
... def foo(a, b=2, c='c', d=None):
...     print(a, b, c, d)

>>> foo(1)
1 2 c None

>>> with scope('foo.b=3'):
...     foo(2)
2 3 c None

classes are also supported:

>>> @param
... class foo:
...     def __init__(self, a, b=2, c='c', d=None):
...         print(a, b, c, d)

>>> obj = foo(1)
1 2 c None

>>> with scope('foo.b=3'):
...     obj = foo(2)
2 3 c None

>>> @param('myns.foo.params')
... def foo(a, b=2, c='c', d=None):
...     print(a, b, c, d)
>>> foo(1)
1 2 c None

>>> with scope('myns.foo.params.b=3'):
...     foo(2)
2 3 c None

>>> with scope('myns.foo.params.b=3'):
...     scope.myns.foo.params.b = 4
...     foo(2)
2 4 c None
Source code in hyperparameter/api.py 
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
def param(
    name_or_func: Union[str, Callable, None],
) -> Union[Callable, Callable[[Callable], Callable]]:
    """Convert keyword arguments into hyperparameters

    Examples
    --------

    >>> @param
    ... def foo(a, b=2, c='c', d=None):
    ...     print(a, b, c, d)

    >>> foo(1)
    1 2 c None

    >>> with scope('foo.b=3'):
    ...     foo(2)
    2 3 c None

    classes are also supported:
    >>> @param
    ... class foo:
    ...     def __init__(self, a, b=2, c='c', d=None):
    ...         print(a, b, c, d)

    >>> obj = foo(1)
    1 2 c None

    >>> with scope('foo.b=3'):
    ...     obj = foo(2)
    2 3 c None

    >>> @param('myns.foo.params')
    ... def foo(a, b=2, c='c', d=None):
    ...     print(a, b, c, d)
    >>> foo(1)
    1 2 c None

    >>> with scope('myns.foo.params.b=3'):
    ...     foo(2)
    2 3 c None

    >>> with scope('myns.foo.params.b=3'):
    ...     scope.myns.foo.params.b = 4
    ...     foo(2)
    2 4 c None
    """

    if callable(name_or_func):
        return param(None)(name_or_func)

    if has_rust_backend:

        def hashed_wrapper(func: Callable) -> Callable:
            predef_kws: Dict[str, int] = {}
            predef_defaults: Dict[str, Any] = {}

            if name_or_func is None:
                namespace = func.__name__
            else:
                namespace = name_or_func

            signature = inspect.signature(func)
            for k, v in signature.parameters.items():
                if v.default != v.empty:
                    name = "{}.{}".format(namespace, k)
                    predef_kws[k] = xxh64(name)
                    predef_defaults[k] = v.default

            @functools.wraps(func)
            def inner(*arg: Any, **kws: Any) -> Any:
                with scope() as hp:
                    for k, v in predef_kws.items():
                        if k not in kws:
                            try:
                                val = hp._storage.get_entry(v)
                                kws[k] = _coerce_with_default(val, predef_defaults[k])
                            except ValueError:
                                pass
                    return func(*arg, **kws)

            inner._auto_param_namespace = namespace  # type: ignore[attr-defined]
            inner._auto_param_wrapped = func  # type: ignore[attr-defined]
            return inner

        return hashed_wrapper

    def wrapper(func: Callable) -> Callable:
        predef_kws: Dict[str, str] = {}
        predef_val: Dict[str, Any] = {}

        if name_or_func is None:
            namespace = func.__name__
        else:
            namespace = name_or_func

        signature = inspect.signature(func)
        for k, v in signature.parameters.items():
            if v.default != v.empty:
                name = "{}.{}".format(namespace, k)
                predef_kws[k] = name
                predef_val[name] = v.default

        @functools.wraps(func)
        def inner(*arg: Any, **kws: Any) -> Any:
            with scope() as hp:
                local_params: Dict[str, Any] = {}
                for k, v in predef_kws.items():
                    if k not in kws:
                        val = getattr(hp(), v).get_or_else(predef_val[v])
                        kws[k] = val
                        local_params[v] = hp.get(v)
                    else:
                        local_params[v] = predef_val[v]
                return func(*arg, **kws)

        inner._auto_param_namespace = namespace  # type: ignore[attr-defined]
        inner._auto_param_wrapped = func  # type: ignore[attr-defined]
        return inner

    return wrapper