Feature update deprecation notes (#437)

* Bump version to 3.0.0-dev and update deprecation notes
* Update changelog with message changes
* Split installation requirements onto own line

Author: hardbyte

CHANGELOG.txt

@@ -1,4 +1,4 @@
-Version 2.3.0
+Version 3.0.0
 ====
 
 Major features
@@ -18,6 +18,8 @@ Major features
 Breaking changes
 ----------------
 
+- Interfaces should no longer override `send_periodic` and instead implement
+  `_send_periodic_internal` #426
 - writing to closed writers is not supported any more (it was supported only for some)
 - the method `Listener.on_message_received()` is now abstract (using `@abc.abstractmethod`)
 - the file in the reader/writer is now always stored in the attribute uniformly called `file`, and not in
@@ -28,6 +30,11 @@ Breaking changes
 Other notable changes
 ---------------------
 
+* can.Message class updated #413
+    - Addition of a Message.equals method.
+    - Deprecate id_type in favor of is_extended_id
+    - documentation, testing and example updates
+    - Addition of support for various builtins: __repr__, __slots__, __copy__
 * IO module updates to bring consistency to the different CAN message writers and readers. #348
     - context manager support for all readers and writers
     - they share a common super class called `BaseIOHandler`
@@ -112,7 +119,7 @@ Version 2.2.0 (2018-06-30)
 * Added synchronized (thread-safe) Bus variant.
 * context manager support for the Bus class.
 * Dropped support for Python 3.3 (officially reached end-of-life in Sept. 2017)
-* Deprecated the old `CAN` module, please use the newer `can` entry point (will be removed in version 2.4)
+* Deprecated the old `CAN` module, please use the newer `can` entry point (will be removed in an upcoming major version)
 
 Version 2.1.0 (2018-02-17)
 =====

can/CAN.py

@@ -4,10 +4,10 @@
 This module was once the core of python-can, containing
 implementations of all the major classes in the library, now
 however all functionality has been refactored out. This API
-is left intact for version 2.0 to 2.3 to aide with migration.
+is left intact for version 2.x to aide with migration.
 
 WARNING:
-This module is deprecated an will get removed in version 2.4.
+This module is deprecated an will get removed in version 3.x.
 Please use ``import can`` instead.
 """
 
@@ -18,14 +18,12 @@
 from can.util import set_logging_level
 from can.io import *
 
-import logging
-
-log = logging.getLogger('can')
+import warnings
 
 # See #267.
 # Version 2.0 - 2.1:    Log a Debug message
 # Version 2.2:          Log a Warning
-# Version 2.3:          Log an Error
-# Version 2.4:          Remove the module
-log.error('Loading python-can via the old "CAN" API is deprecated since v2.0 an will get removed in v2.4. '
-            'Please use `import can` instead.')
+# Version 3.x:          DeprecationWarning
+# Version 4.0:          Remove the module
+warnings.warn('Loading python-can via the old "CAN" API is deprecated since v3.0 an will get removed in v4.0 '
+              'Please use `import can` instead.', DeprecationWarning)

can/__init__.py

@@ -8,7 +8,7 @@
 
 import logging
 
-__version__ = "2.3.0-dev"
+__version__ = "3.0.0-dev"
 
 log = logging.getLogger('can')
 

can/broadcastmanager.py

@@ -11,7 +11,7 @@
 import logging
 import threading
 import time
-
+import warnings
 
 log = logging.getLogger('can.bcm')
 
@@ -153,6 +153,6 @@ def send_periodic(bus, message, period, *args, **kwargs):
     :param float period: The minimum time between sending messages.
     :return: A started task instance
     """
-    log.warning("The function `can.send_periodic` is deprecated and will " +
-                "be removed in version 3.0. Please use `can.Bus.send_periodic` instead.")
+    warnings.warn("The function `can.send_periodic` is deprecated and will " +
+                  "be removed in an upcoming version. Please use `can.Bus.send_periodic` instead.", DeprecationWarning)
     return bus.send_periodic(message, period, *args, **kwargs)

can/interface.py

@@ -21,7 +21,7 @@
 
 if 'linux' in sys.platform:
     # Deprecated and undocumented access to SocketCAN cyclic tasks
-    # Will be removed in version 3.0
+    # Will be removed in version 4.0
     from can.interfaces.socketcan import CyclicSendTask, MultiRateCyclicSendTask
 
 # Required by "detect_available_configs" for argument interpretation

can/interfaces/__init__.py

@@ -4,11 +4,9 @@
 Interfaces contain low level implementations that interact with CAN hardware.
 """
 
-import logging
-
+import warnings
 from pkg_resources import iter_entry_points
 
-logger = logging.getLogger(__name__)
 
 # interface_name => (module, classname)
 BACKENDS = {
@@ -31,10 +29,10 @@
     for interface in iter_entry_points('can.interface')
 })
 
-# Old entry point name. May be removed in 3.0.
+# Old entry point name. May be removed >3.0.
 for interface in iter_entry_points('python_can.interface'):
     BACKENDS[interface.name] = (interface.module_name, interface.attrs[0])
-    logger.warning('%s is using the deprecated python_can.interface entry point. '
-                   'Please change to can.interface instead.', interface.name)
+    warnings.warn('{} is using the deprecated python_can.interface entry point. '.format(interface.name) +
+                  'Please change to can.interface instead.', DeprecationWarning)
 
 VALID_INTERFACES = frozenset(list(BACKENDS.keys()) + ['socketcan_native', 'socketcan_ctypes'])

can/util.py

@@ -12,6 +12,8 @@
 import platform
 import re
 import logging
+import warnings
+
 try:
     from configparser import ConfigParser
 except ImportError:
@@ -184,11 +186,11 @@ def load_config(path=None, config=None, context=None):
         if key not in config:
             config[key] = None
 
-    # deprecated socketcan types
+    # Handle deprecated socketcan types
     if config['interface'] in ('socketcan_native', 'socketcan_ctypes'):
-        # Change this to a DeprecationWarning in future 2.x releases
-        # Remove completely in 3.0
-        log.warning('%s is deprecated, use socketcan instead', config['interface'])
+        # DeprecationWarning in 3.x releases
+        # TODO: Remove completely in 4.0
+        warnings.warn('{} is deprecated, use socketcan instead'.format(config['interface']), DeprecationWarning)
         config['interface'] = 'socketcan'
 
     if config['interface'] not in VALID_INTERFACES:

doc/bcm.rst

@@ -49,7 +49,7 @@ Functional API
 
 .. warning::
     The functional API in :func:`can.broadcastmanager.send_periodic` is now deprecated
-    and will be removed in version 3.0.
+    and will be removed in version 4.0.
     Use the object oriented API via :meth:`can.BusABC.send_periodic` instead.
 
 .. autofunction:: can.broadcastmanager.send_periodic

doc/interfaces/socketcan.rst

@@ -10,7 +10,7 @@ The full documentation for socketcan can be found in the kernel docs at
     Versions before 2.2 had two different implementations named
     ``socketcan_ctypes`` and ``socketcan_native``. These are now
     deprecated and the aliases to ``socketcan`` will be removed in
-    version 3.0. Future 2.x release may raise a DeprecationWarning.
+    version 4.0.  3.x releases raise a DeprecationWarning.
 
 
 Socketcan Quickstart

setup.py

@@ -99,7 +99,9 @@
     # see https://www.python.org/dev/peps/pep-0345/#version-specifiers
     python_requires=">=2.7,!=3.0,!=3.1,!=3.2,!=3.3",
     install_requires=[
-        'wrapt~=1.10', 'typing', 'windows-curses;platform_system=="Windows"',
+        'wrapt~=1.10',
+        'typing',
+        'windows-curses;platform_system=="Windows"',
     ],
     extras_require=extras_require,