Refactor utils

Fixes #1598

This refactors utils to make them private the most as possible

Author: ocelotl

.github/workflows/test.yml

@@ -10,7 +10,7 @@ env:
   # Otherwise, set variable to the commit of your branch on
   # opentelemetry-python-contrib which is compatible with these Core repo
   # changes.
-  CONTRIB_REPO_SHA: 99d6a2d7987d0f2cdde04319627c86fc0a465351
+  CONTRIB_REPO_SHA: eb8b85327908ea9da66224790df01a92975c3102
 
 jobs:
   build:
@@ -56,7 +56,7 @@ jobs:
         run: pip install -U tox-factor
       - name: Cache tox environment
         # Preserves .tox directory between runs for faster installs
-        uses: actions/cache@v2
+        uses: actions/cache@v1
         with:
           path: .tox
           key: tox-cache-${{ env.RUN_MATRIX_COMBINATION }}-${{ hashFiles('tox.ini', 'dev-requirements.txt') }}-core
@@ -109,7 +109,7 @@ jobs:
         run: pip install -U tox
       - name: Cache tox environment
         # Preserves .tox directory between runs for faster installs
-        uses: actions/cache@v1
+        uses: actions/cache@v2
         with:
           path: .tox
           key: tox-cache-${{ matrix.tox-environment }}-${{ hashFiles('tox.ini', 'dev-requirements.txt') }}-core
@@ -159,7 +159,7 @@ jobs:
         run: pip install -U tox-factor
       - name: Cache tox environment
         # Preserves .tox directory between runs for faster installs
-        uses: actions/cache@v2
+        uses: actions/cache@v1
         with:
           path: .tox
           key: tox-cache-${{ matrix.python-version }}-${{ matrix.package }}-${{ matrix.os }}-${{ hashFiles('tox.ini', 'dev-requirements.txt') }}-contrib
@@ -191,7 +191,7 @@ jobs:
         run: pip install -U tox
       - name: Cache tox environment
         # Preserves .tox directory between runs for faster installs
-        uses: actions/cache@v2
+        uses: actions/cache@v1
         with:
           path: .tox
           key: tox-cache-${{ matrix.tox-environment }}-${{ hashFiles('tox.ini', 'dev-requirements.txt') }}-contrib

opentelemetry-api/src/opentelemetry/trace/__init__.py

@@ -74,13 +74,14 @@
 """
 
 
-import abc
-import enum
-import typing
+from abc import ABC, abstractmethod
 from contextlib import contextmanager
+from enum import Enum
 from logging import getLogger
+from typing import Iterator, Optional, Sequence, cast
 
 from opentelemetry.context.context import Context
+from opentelemetry.environment_variables import OTEL_PYTHON_TRACER_PROVIDER
 from opentelemetry.trace.propagation import (
     get_current_span,
     set_span_in_context,
@@ -102,12 +103,12 @@
 )
 from opentelemetry.trace.status import Status
 from opentelemetry.util import types
-from opentelemetry.util.providers import _load_trace_provider
+from opentelemetry.util._providers import _load_provider
 
 logger = getLogger(__name__)
 
 
-class LinkBase(abc.ABC):
+class LinkBase(ABC):
     def __init__(self, context: "SpanContext") -> None:
         self._context = context
 
@@ -116,7 +117,7 @@ def context(self) -> "SpanContext":
         return self._context
 
     @property
-    @abc.abstractmethod
+    @abstractmethod
     def attributes(self) -> types.Attributes:
         pass
 
@@ -140,10 +141,10 @@ def attributes(self) -> types.Attributes:
         return self._attributes
 
 
-_Links = typing.Optional[typing.Sequence[Link]]
+_Links = Optional[Sequence[Link]]
 
 
-class SpanKind(enum.Enum):
+class SpanKind(Enum):
     """Specifies additional details on how this span relates to its parent span.
 
     Note that this enumeration is experimental and likely to change. See
@@ -172,8 +173,8 @@ class SpanKind(enum.Enum):
     CONSUMER = 4
 
 
-class TracerProvider(abc.ABC):
-    @abc.abstractmethod
+class TracerProvider(ABC):
+    @abstractmethod
     def get_tracer(
         self,
         instrumenting_module_name: str,
@@ -217,7 +218,7 @@ def get_tracer(
         return DefaultTracer()
 
 
-class Tracer(abc.ABC):
+class Tracer(ABC):
     """Handles span creation and in-process context propagation.
 
     This class provides methods for manipulating the context, creating spans,
@@ -228,15 +229,15 @@ class Tracer(abc.ABC):
     # This is the default behavior when creating spans.
     CURRENT_SPAN = DefaultSpan(INVALID_SPAN_CONTEXT)
 
-    @abc.abstractmethod
+    @abstractmethod
     def start_span(
         self,
         name: str,
-        context: typing.Optional[Context] = None,
+        context: Optional[Context] = None,
         kind: SpanKind = SpanKind.INTERNAL,
         attributes: types.Attributes = None,
         links: _Links = None,
-        start_time: typing.Optional[int] = None,
+        start_time: Optional[int] = None,
         record_exception: bool = True,
         set_status_on_exception: bool = True,
     ) -> "Span":
@@ -283,19 +284,19 @@ def start_span(
         """
 
     @contextmanager  # type: ignore
-    @abc.abstractmethod
+    @abstractmethod
     def start_as_current_span(
         self,
         name: str,
-        context: typing.Optional[Context] = None,
+        context: Optional[Context] = None,
         kind: SpanKind = SpanKind.INTERNAL,
         attributes: types.Attributes = None,
         links: _Links = None,
-        start_time: typing.Optional[int] = None,
+        start_time: Optional[int] = None,
         record_exception: bool = True,
         set_status_on_exception: bool = True,
         end_on_exit: bool = True,
-    ) -> typing.Iterator["Span"]:
+    ) -> Iterator["Span"]:
         """Context manager for creating a new span and set it
         as the current span in this tracer's context.
 
@@ -350,10 +351,10 @@ def start_as_current_span(
         """
 
     @contextmanager  # type: ignore
-    @abc.abstractmethod
+    @abstractmethod
     def use_span(
         self, span: "Span", end_on_exit: bool = False,
-    ) -> typing.Iterator[None]:
+    ) -> Iterator[None]:
         """Context manager for setting the passed span as the
         current span in the context, as well as resetting the
         context back upon exiting the context manager.
@@ -381,11 +382,11 @@ class DefaultTracer(Tracer):
     def start_span(
         self,
         name: str,
-        context: typing.Optional[Context] = None,
+        context: Optional[Context] = None,
         kind: SpanKind = SpanKind.INTERNAL,
         attributes: types.Attributes = None,
         links: _Links = None,
-        start_time: typing.Optional[int] = None,
+        start_time: Optional[int] = None,
         record_exception: bool = True,
         set_status_on_exception: bool = True,
     ) -> "Span":
@@ -396,22 +397,22 @@ def start_span(
     def start_as_current_span(
         self,
         name: str,
-        context: typing.Optional[Context] = None,
+        context: Optional[Context] = None,
         kind: SpanKind = SpanKind.INTERNAL,
         attributes: types.Attributes = None,
         links: _Links = None,
-        start_time: typing.Optional[int] = None,
+        start_time: Optional[int] = None,
         record_exception: bool = True,
         set_status_on_exception: bool = True,
         end_on_exit: bool = True,
-    ) -> typing.Iterator["Span"]:
+    ) -> Iterator["Span"]:
         # pylint: disable=unused-argument,no-self-use
         yield INVALID_SPAN
 
     @contextmanager  # type: ignore
     def use_span(
         self, span: "Span", end_on_exit: bool = False,
-    ) -> typing.Iterator[None]:
+    ) -> Iterator[None]:
         # pylint: disable=unused-argument,no-self-use
         yield
 
@@ -422,7 +423,7 @@ def use_span(
 def get_tracer(
     instrumenting_module_name: str,
     instrumenting_library_version: str = "",
-    tracer_provider: typing.Optional[TracerProvider] = None,
+    tracer_provider: Optional[TracerProvider] = None,
 ) -> "Tracer":
     """Returns a `Tracer` for use by the given instrumentation library.
 
@@ -458,8 +459,10 @@ def get_tracer_provider() -> TracerProvider:
     global _TRACER_PROVIDER  # pylint: disable=global-statement
 
     if _TRACER_PROVIDER is None:
-        _TRACER_PROVIDER = _load_trace_provider("tracer_provider")
-
+        _TRACER_PROVIDER = cast(  # type: ignore
+            "TracerProvider",
+            _load_provider(OTEL_PYTHON_TRACER_PROVIDER, "tracer_provider"),
+        )
     return _TRACER_PROVIDER
 
 

opentelemetry-api/src/opentelemetry/trace/span.py

@@ -7,16 +7,55 @@
 
 from opentelemetry.trace.status import Status
 from opentelemetry.util import types
-from opentelemetry.util.tracestate import (
-    _DELIMITER_PATTERN,
-    _MEMBER_PATTERN,
-    _TRACECONTEXT_MAXIMUM_TRACESTATE_KEYS,
-    _is_valid_pair,
+
+# The key MUST begin with a lowercase letter or a digit,
+# and can only contain lowercase letters (a-z), digits (0-9),
+# underscores (_), dashes (-), asterisks (*), and forward slashes (/).
+# For multi-tenant vendor scenarios, an at sign (@) can be used to
+# prefix the vendor name. Vendors SHOULD set the tenant ID
+# at the beginning of the key.
+
+# key = ( lcalpha ) 0*255( lcalpha / DIGIT / "_" / "-"/ "*" / "/" )
+# key = ( lcalpha / DIGIT ) 0*240( lcalpha / DIGIT / "_" / "-"/ "*" / "/" ) "@" lcalpha 0*13( lcalpha / DIGIT / "_" / "-"/ "*" / "/" )
+# lcalpha = %x61-7A ; a-z
+
+_KEY_FORMAT = (
+    r"[a-z][_0-9a-z\-\*\/]{0,255}|"
+    r"[a-z0-9][_0-9a-z\-\*\/]{0,240}@[a-z][_0-9a-z\-\*\/]{0,13}"
+)
+_KEY_PATTERN = re.compile(_KEY_FORMAT)
+
+# The value is an opaque string containing up to 256 printable
+# ASCII [RFC0020] characters (i.e., the range 0x20 to 0x7E)
+# except comma (,) and (=).
+# value    = 0*255(chr) nblk-chr
+# nblk-chr = %x21-2B / %x2D-3C / %x3E-7E
+# chr      = %x20 / nblk-chr
+
+_VALUE_FORMAT = (
+    r"[\x20-\x2b\x2d-\x3c\x3e-\x7e]{0,255}[\x21-\x2b\x2d-\x3c\x3e-\x7e]"
 )
+_VALUE_PATTERN = re.compile(_VALUE_FORMAT)
 
+
+_TRACECONTEXT_MAXIMUM_TRACESTATE_KEYS = 32
+_delimiter_pattern = re.compile(r"[ \t]*,[ \t]*")
+_member_pattern = re.compile(
+    "({})(=)({})[ \t]*".format(_KEY_FORMAT, _VALUE_FORMAT)
+)
 _logger = logging.getLogger(__name__)
 
 
+def _is_valid_pair(key: str, value: str) -> bool:
+
+    return (
+        isinstance(key, str)
+        and _KEY_PATTERN.fullmatch(key) is not None
+        and isinstance(value, str)
+        and _VALUE_PATTERN.fullmatch(value) is not None
+    )
+
+
 class Span(abc.ABC):
     """A span represents a single operation within a trace."""
 
@@ -314,11 +353,11 @@ def from_header(cls, header_list: typing.List[str]) -> "TraceState":
         """
         pairs = OrderedDict()
         for header in header_list:
-            for member in re.split(_DELIMITER_PATTERN, header):
+            for member in re.split(_delimiter_pattern, header):
                 # empty members are valid, but no need to process further.
                 if not member:
                     continue
-                match = _MEMBER_PATTERN.fullmatch(member)
+                match = _member_pattern.fullmatch(member)
                 if not match:
                     _logger.warning(
                         "Member doesn't match the w3c identifiers format %s",

opentelemetry-api/src/opentelemetry/util/providers.py renamed to opentelemetry-api/src/opentelemetry/util/_providers.py

@@ -12,33 +12,19 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-import time
 from logging import getLogger
 from os import environ
 from typing import TYPE_CHECKING, Union, cast
 
 from pkg_resources import iter_entry_points
 
-from opentelemetry.environment_variables import OTEL_PYTHON_TRACER_PROVIDER
-
 if TYPE_CHECKING:
     from opentelemetry.trace import TracerProvider
 
 Provider = Union["TracerProvider"]
 
 logger = getLogger(__name__)
 
-# Since we want API users to be able to provide timestamps,
-# this needs to be in the API.
-
-try:
-    time_ns = time.time_ns
-# Python versions < 3.7
-except AttributeError:
-
-    def time_ns() -> int:
-        return int(time.time() * 1e9)
-
 
 def _load_provider(
     provider_environment_variable: str, provider: str
@@ -60,10 +46,3 @@ def _load_provider(
     except Exception:  # pylint: disable=broad-except
         logger.error("Failed to load configured provider %s", provider)
         raise
-
-
-def _load_trace_provider(provider: str) -> "TracerProvider":
-    return cast(  # type: ignore
-        "TracerProvider",
-        _load_provider(OTEL_PYTHON_TRACER_PROVIDER, provider),
-    )

opentelemetry-api/src/opentelemetry/util/time.py

@@ -0,0 +1,27 @@
+# Copyright The OpenTelemetry Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from sys import version_info
+
+if version_info.minor < 7:
+    from time import time
+
+    def time_ns() -> int:
+        # FIXME this approach can have precision problems as explained here:
+        # https://github.com/open-telemetry/opentelemetry-python/issues/1594
+        return int(time() * 1e9)
+
+
+else:
+    from time import time_ns  # pylint: disable=unused-import