Manual sync: v0.1a1.

Author: Oberon00

MANIFEST.in

@@ -1,5 +1,6 @@
 prune test
 graft src
+global-exclude onesdk_shared.*
 global-exclude *.pyc
 global-exclude *.pyo
 global-exclude __pycache__/*

README.md

@@ -1,47 +1,141 @@
-**Disclaimer: This SDK is currently in early access and still work in
-progress.**
-
+**Disclaimer: This SDK is currently still work in progress.
+Using the OneAgent SDK for Python is COMPLETELY UNSUPPORTED at this stage!**
 
 # Dynatrace OneAgent SDK for Python
 
 This SDK enables Dynatrace customers to extend request level visibility into
-Python applications.
-
-It provides the Python implementation of the [Dynatrace OneAgent
-SDK](https://github.com/Dynatrace/OneAgent-SDK). 
-
-
-## Package contents
-
-- `LICENSE`: License under which the whole SDK and sample applications are
-  published.
-- `src/`: Actual source code of the Python OneAgent SDK.
-- `docs/`: Source files for the ([Sphinx](https://sphinx-doc.org)-based) HTML
-  documentation. For the actual, readable documentation, see
-  [here](#documenation).
-- `tests/`: Contains tests that are useful (only) for developers wanting
-  contribute to the SDK itself.
-- `setup.py`, `setup.cfg`, `MANIFEST.in`: Development Files required for
-  creating e.g. the PyPI package for the Python OneAgent SDK.
-- `tox.ini`, `pylintrc`: Supporting files for developing the SDK itself. See
-  <https://tox.readthedocs.io/en/latest/> and <https://www.pylint.org/>.
-
+Python applications. It provides the Python implementation of the [Dynatrace OneAgent
+SDK](https://github.com/Dynatrace/OneAgent-SDK).
 
 ## Features
 
-Dynatrace OneAgent SDK for Python currently implements support for the following
-features (corresponding to features specified in [Dynatrace OneAgent
+The Dynatrace OneAgent SDK for Python currently supports the following features
+(corresponding to features specified in [Dynatrace OneAgent
 SDK](https://github.com/Dynatrace/OneAgent-SDK)):
 
 - Outgoing and incoming remote calls
 - SQL Database requests
 - Incoming web requests
 
+## Requirements
+
+The SDK supports Python 2 ≥ 2.7 and Python 3 ≥ 3.4. Only the official CPython
+(that is, the "normal" Python, i.e. the Python implementation from
+<https://python.org>) is supported.
+
+The Dynatrace OneAgent SDK for Python includes the [Dynatrace OneAgent SDK for
+C/C++](https://github.com/Dynatrace/OneAgent-SDK-for-C). See
+[here](https://github.com/Dynatrace/OneAgent-SDK-for-C#dynatrace-oneagent-sdk-for-cc-requirements)
+for its requirements, which also apply to the SDK for Python.
+
+The version of the SDK for C/C++ that is included in each version of the SDK for
+Python is shown in the following table. The SDK for C/C++'s requirement for the
+Dynatrace OneAgent is also shown here, for your convenience (it is the same that
+is [listed in the OneAgent SDK for C/C++'s
+documentation](https://github.com/Dynatrace/OneAgent-SDK-for-C/blob/master/README.md#compatibility-of-dynatrace-oneagent-sdk-for-cc-releases-with-oneagent-releases)).
+
+|OneAgent SDK for Python|OneAgent SDK for C/C++|Dynatrace OneAgent|
+|:----------------------|:---------------------|:-----------------|
+|0.1                    |1.1.0                 |≥1.141            |
+
+## Using the OneAgent SDK for Python in your application
+
+<a id="installation"></a>
+
+Once the oneagent SDK is released to PyPI, you will be able to just do `python
+-m pip install oneagent-sdk`, to install the SDK.
+
+While the SDK has no public release, please use the wheels provided on the
+[GitHub releases
+page](https://github.com/Dynatrace/OneAgent-SDK-for-Python/releases), by
+ giving the additional option
+`--find-links DISTIDXURL` to pip (where `DISTIDXURL` is the URL linked on the
+GitHub release. This approach also works when
+installing packages that depend on the oneagent-sdk package, e.g. `pip install
+--find-links DISTIDXURL my-pkg-that-uses-oneagent-sdk`. (Note that this means that
+you cannot just use `python setup.py install` for the dependent package. If you
+only have a directoy with `setup.py` instead of a proper distribution, use
+`python setup.py sdist` and then `pip install --find-links dist --find-links
+DISTIDXURL PACKAGENAME`.)
+
+To verify your installation, execute
+
+```bash
+python -c "import oneagent; print(oneagent.try_init())"
+```
+
+If everything worked, you should get some output ending with
+`InitResult(status=0, error=None)`. Otherwise, see
+[Troubleshooting](#troubleshooting).
+
+The output should end with `InitResult(status=0, error=None)`.
+
+You then need to load the SDK into the application and add code that traces your
+application using the SDK. For a quick “Hello World” that should give you a Path
+in the Dynatrace UI, try this:
+
+```python
+import oneagent
+from oneagent.sdk import SDK
+
+if not oneagent.try_init():
+    print('Error initializing OneAgent SDK.')
+
+with SDK.get().trace_incoming_remote_call('method', 'service', 'endpoint'):
+    pass
+```
+
+For this, follow the <tests/onesdksamplepy.py>
+example (see also the
+[documentation](https://dynatrace.github.io/OneAgent-SDK-for-Python/quickstart.html).
 
 ## Documentation
 
-The reference documentation is included in this package. The most recent version
-is also available online at <https://dynatrace.github.io/OneAgent-SDK-for-Python/>
+The most recent version of the documentation can be viewed at
+<https://dynatrace.github.io/OneAgent-SDK-for-Python/>.
 
 A high level documentation/description of OneAgent SDK concepts is available at
 <https://github.com/Dynatrace/OneAgent-SDK/>.
+
+## Troubleshooting
+
+To debug your OneSDK installation, execute the following Python code:
+
+```python
+import oneagent
+oneagent.logger.setLevel(0)
+init_result = oneagent.try_init(['loglevelsdk=finest', 'loglevel=finest'])
+print('InitResult=' + repr(init_result))
+```
+
+If you get output containing `InitResult=InitResult(status=0, error=None)`, your
+installation should be fine.
+
+Otherwise, hopefully the output is helpful in determining the issue.
+
+Known gotchas:
+
+* `ImportError` or `ModuleNotFoundError` in line 1 that says that there is no
+  module named `oneagent`.
+
+  Make sure that the `pip install` or equivalent succeeded (see
+  [here](#installation)). Also make sure you use the `pip` corresponding to your
+  `python` (if in doubt, use `python -m pip` instead of `pip` for installing).
+
+## Repository contents
+
+If you are viewing the [GitHub
+repository](https://github.com/Dynatrace/OneAgent-SDK-for-Python), you will see:
+
+- `LICENSE`: License under which the whole SDK and sample applications are
+  published.
+- `src/`: Actual source code of the Python OneAgent SDK.
+- `docs/`: Source files for the ([Sphinx](https://sphinx-doc.org)-based) HTML
+  documentation. For the actual, readable documentation, see
+  [here](#documenation).
+- `tests/`, `test-util-src/`: Contains tests and test support files that are
+  useful (only) for developers wanting contribute to the SDK itself.
+- `setup.py`, `setup.cfg`, `MANIFEST.in`, `project.toml`: Development files
+  required for creating e.g. the PyPI package for the Python OneAgent SDK.
+- `tox.ini`, `pylintrc`: Supporting files for developing the SDK itself. See
+  <https://tox.readthedocs.io/en/latest/> and <https://www.pylint.org/>.

docs/conf.py

@@ -21,6 +21,8 @@
 # import sys
 # sys.path.insert(0, os.path.abspath('.'))
 
+from oneagent import __version__ as version
+
 # Fix spurious "= None" for instance attributes
 # https://github.com/sphinx-doc/sphinx/issues/2044
 from sphinx.ext.autodoc import (
@@ -69,9 +71,9 @@ def iad_add_directive_header(self, sig):
 # built documents.
 #
 # The short X.Y version.
-version = ''
+#version = '' #  see import above
 # The full version, including alpha/beta/rc tags.
-release = ''
+release = version
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

project.toml

@@ -0,0 +1,5 @@
+# https://www.python.org/dev/peps/pep-0518/
+[build-system]
+# http://setuptools.readthedocs.io/en/latest/history.html#v36-4-0
+# Required for Description-Content-Type
+requires = ["setuptools>=36.4"]

setup.py

@@ -1,10 +1,17 @@
 #! /usr/bin/env python3
 
+# Beware when cross-building 64/32 bit:
+# When using --plat-name to override this, make sure to `rm -r build` othewise
+# files from the wrong platform might be reused.
+# Also, on Linux because of https://bugs.python.org/issue18987, using a 32 bit
+# Python on a 64 bit OS is not enough to change the platform tag.
+
 from __future__ import print_function
 
 import io
 import os
 from os import path
+import re
 
 # https://github.com/PyCQA/pylint/issues/73
 #pylint:disable=no-name-in-module,import-error
@@ -24,10 +31,26 @@
 
 CSDK_ENV_NAME = 'DT_PYSDK_CSDK_PATH'
 
-with io.open('README.md', encoding='utf-8') as readmefile:
+_THIS_DIR = path.dirname(path.abspath(__file__))
+
+with io.open(path.join(_THIS_DIR, 'README.md'), encoding='utf-8') as readmefile:
     long_description = readmefile.read()
 del readmefile
 
+VER_RE = re.compile(r"^__version__ = '([^']+)'$")
+
+verfilepath = path.join(_THIS_DIR, 'src/oneagent/__init__.py')
+with io.open(verfilepath, encoding='utf-8') as verfile:
+    for line in verfile:
+        match = VER_RE.match(line)
+        if match:
+            __version__ = match.group(1)
+            break
+    else:
+        raise AssertionError('Version not found in src/oneagent/__init__.py')
+del match, verfile, verfilepath, VER_RE
+
+
 def compilefile(fname, mode='exec'):
     with open(fname) as srcfile:
         codestr = srcfile.read()
@@ -63,7 +86,8 @@ def get_tag(self):
 def get_dll_info(plat_name):
     dll_info = {}
     #pylint:disable=exec-used
-    exec(compilefile('src/oneagent/_impl/native/sdkdllinfo.py'), dll_info)
+    infopath = path.join(_THIS_DIR, 'src/oneagent/_impl/native/sdkdllinfo.py')
+    exec(compilefile(infopath), dll_info)
     if plat_name:
         is_win32 = plat_name.startswith('win')
         is_64bit = plat_name.endswith('64')
@@ -158,39 +182,44 @@ def has_ext_modules(self): #pylint:disable=no-self-use
 if bdist_wheel is not None:
     cmdclss['bdist_wheel'] = BdistWheel
 
-setup(
-    packages=find_packages('src'),
-    package_dir={'': 'src'},
-    include_package_data=True,
-    zip_safe=True,
-    python_requires='>=2.7,!=3.0,!=3.1,!=3.2,!=3.3',
-    cmdclass=cmdclss,
-    name='oneagent-sdk',
-    version='0.1',
-    distclass=BinaryDistribution,
-
-    description='Dynatrace OneAgent SDK for Python',
-    long_description=long_description,
-    url='https://www.dynatrace.com/',
-    maintainer='Dynatrace LLC',
-    maintainer_email='dynatrace.oneagent.sdk@dynatrace.com',
-    license='Apache License 2.0',
-    classifiers=[
-        'Development Status :: 2 - Pre-Alpha',
-        'Intended Audience :: Developers',
-        'License :: OSI Approved :: Apache Software License', # 2.0
-        'Programming Language :: Python',
-        'Programming Language :: Python :: 2',
-        'Programming Language :: Python :: 2.7',
-        'Programming Language :: Python :: 3',
-        'Programming Language :: Python :: 3.3',
-        'Programming Language :: Python :: 3.4',
-        'Programming Language :: Python :: 3.5',
-        'Programming Language :: Python :: 3.6',
-        'Programming Language :: Python :: Implementation :: CPython',
-        #'Programming Language :: Python :: Implementation :: PyPy',
-        'Operating System :: POSIX :: Linux',
-        'Operating System :: Microsoft :: Windows',
-        'Topic :: Software Development :: Libraries',
-        'Topic :: System :: Monitoring'
-    ])
+def main():
+    setup(
+        packages=find_packages('src'),
+        package_dir={'': 'src'},
+        include_package_data=True,
+        zip_safe=True,
+        python_requires='>=2.7,!=3.0,!=3.1,!=3.2,!=3.3',
+        cmdclass=cmdclss,
+        name='oneagent-sdk',
+        version=__version__,
+        distclass=BinaryDistribution,
+
+        description='Dynatrace OneAgent SDK for Python',
+        long_description=long_description,
+        long_description_content_type='text/markdown',
+        url='https://www.dynatrace.com/',
+        maintainer='Dynatrace LLC',
+        maintainer_email='dynatrace.oneagent.sdk@dynatrace.com',
+        license='Apache License 2.0',
+        classifiers=[
+            'Development Status :: 2 - Pre-Alpha',
+            'Intended Audience :: Developers',
+            'License :: OSI Approved :: Apache Software License', # 2.0
+            'Programming Language :: Python',
+            'Programming Language :: Python :: 2',
+            'Programming Language :: Python :: 2.7',
+            'Programming Language :: Python :: 3',
+            'Programming Language :: Python :: 3.3',
+            'Programming Language :: Python :: 3.4',
+            'Programming Language :: Python :: 3.5',
+            'Programming Language :: Python :: 3.6',
+            'Programming Language :: Python :: Implementation :: CPython',
+            #'Programming Language :: Python :: Implementation :: PyPy',
+            'Operating System :: POSIX :: Linux',
+            'Operating System :: Microsoft :: Windows',
+            'Topic :: Software Development :: Libraries',
+            'Topic :: System :: Monitoring'
+        ])
+
+if __name__ == '__main__':
+    main()

src/oneagent/__init__.py

@@ -6,9 +6,10 @@
     The :class:`logging.Logger` on which managed Python SDK messages will be
     written.
 
-    This logger is not specially configured in any way. Unless you configure
-    this or the root logger yourself, you won't see any output. See
-    :ref:`logging-basic-tutorial` in the official Python documentation.
+    This logger has set the log level so that no messages are displayed by
+    default. Use e.g. :code:`oneagent.logger.setLevel(logging.INFO)` to see
+    them. See :ref:`logging-basic-tutorial` in the official Python
+    documentation for more on configuring the logger.
 
 .. class:: InitResult
 
@@ -70,7 +71,12 @@
 from .common import SDKError, ErrorCode
 from ._impl.native import nativeagent
 
+# See https://www.python.org/dev/peps/pep-0440/ "Version Identification and
+# Dependency Specification"
+__version__ = '0.1a1'
+
 logger = logging.getLogger('py_sdk')
+logger.setLevel(logging.CRITICAL + 1) # Disabled by default
 
 class InitResult(namedtuple('InitResult', 'status error')):
     __slots__ = ()

src/oneagent/_impl/native/sdkctypesiface.py

@@ -166,7 +166,7 @@ def __init__(self, libname):
         initfn(
             'stub_set_logging_level',
             (log_level_t,),
-            result_t)
+            None)
         initfn(
             'stub_default_logging_function',
             (log_level_t, XStrPInArg),

src/oneagent/_impl/native/sdkmockiface.py

@@ -337,8 +337,6 @@ def stub_set_logging_level(self, level):
         _typecheck(level, int)
         if level < MessageSeverity.FINEST or level > MessageSeverity.DEBUG:
             warnings.warn('Bad message severity level.', RuntimeWarning)
-            return ErrorCode.INVALID_ARGUMENT
-        return ErrorCode.SUCCESS
 
     def stub_default_logging_function(self, level, msg):
         print('[OneSDK:Mock]', level, msg, file=sys.stderr)