Merge #448

448: Deprecate the visa module r=MatthieuDartiailh a=MatthieuDartiailh

Address #447

Co-authored-by: MatthieuDartiailh <marul@laposte.net>

CHANGES

@@ -5,7 +5,9 @@ PyVISA Changelog
 -----------------
 
 - Make the library less biased towards National Instrument by referring to IVI
-  where relevant PR #456
+  where relevant. In particular rename the @ni backend to @ivi PR #456
+- Deprecate the `visa` module that is causing issue with the VISA payment
+  processing package PR #448
 
 1.10.1 (2019-09-11)
 -------------------

docs/source/advanced/architecture.rst

@@ -67,8 +67,8 @@ Calling middle- and low-level functions
 
 After you have instantiated the |ResourceManager|::
 
-    >>> import visa
-    >>> rm = visa.ResourceManager()
+    >>> import pyvisa
+    >>> rm = pyvisa.ResourceManager()
 
 you can access the corresponding ``VisaLibrary`` instance under the |visalib|
 attribute.

docs/source/advanced/backends.rst

@@ -24,26 +24,26 @@ By default, it calls the library that is installed on your system as VISA librar
 You can specify the backend to use when you instantiate the resource manager
 using the ``@`` symbol. Remembering that **ivi** is the default, this::
 
-    >>> import visa
-    >>> rm = visa.ResourceManager()
+    >>> import pyvisa
+    >>> rm = pyvisa.ResourceManager()
 
 is the same as this::
 
-    >>> import visa
-    >>> rm = visa.ResourceManager('@ivi')
+    >>> import pyvisa
+    >>> rm = pyvisa.ResourceManager('@ivi')
 
 You can still provide the path to the library if needed::
 
-    >>> import visa
-    >>> rm = visa.ResourceManager('/path/to/lib@ivi')
+    >>> import pyvisa
+    >>> rm = pyvisa.ResourceManager('/path/to/lib@ivi')
 
 Under the hood, the |ResourceManager| looks for the requested backend and
 instantiate the VISA library that it provides.
 
 PyVISA locates backends by name. If you do:
 
-    >>> import visa
-    >>> rm = visa.ResourceManager('@somename')
+    >>> import pyvisa
+    >>> rm = pyvisa.ResourceManager('@somename')
 
 PyVISA will try to import a package/module named ``pyvisa-somename`` which
 should be installed in your system. This is a loosely coupled configuration
@@ -53,7 +53,7 @@ actually try to use it.
 You can list the installed backends by running the following code in the
 command line::
 
-    python -m visa info
+    pyvisa-info
 
 
 Developing a new Backend
@@ -70,7 +70,7 @@ What does a minimum backend looks like? Quite simple::
 
 Additionally you can provide a staticmethod named `get_debug_info` that should
 return a dictionary of debug information which is printed when you call
-``python -m visa info`` or ``pyvisa-info``
+``pyvisa-info``
 
 .. note::
 

docs/source/faq/contributing.rst

@@ -14,13 +14,13 @@ questions. In some cases, platform specific information is required. If you
 think this is the case, run the following command and paste the output into
 the issue::
 
-    python -m visa info
+    pyvisa-info
 
 It is useful that you also provide the log output. To obtain it, add the
 following lines to your code::
 
-    import visa
-    visa.log_to_screen()
+    import pyvisa
+    pyvisa.log_to_screen()
 
 If your issue concern a specific instrument please be sure to indicate the
 manufacturer and the model.

docs/source/faq/faq.rst

@@ -36,8 +36,8 @@ I have an error in my program and I am having trouble to fix it
 PyVISA provides useful logs of all operations. Add the following commands to
 your program and run it again::
 
-    import visa
-    visa.log_to_screen()
+    import pyvisa
+    pyvisa.log_to_screen()
 
 
 I found a bug, how can I report it?
@@ -47,7 +47,7 @@ Please report it on the `Issue Tracker`_, including operating system, python
 version and library version. In addition you might add supporting information
 by pasting the output of this command::
 
-    python -m visa info
+    pyvisa-info
 
 
 Error: Image not found
@@ -73,6 +73,16 @@ or::
 or creating a configuration file as described in :ref:`intro-configuring`.
 
 
+Error: `visa` module has no attribute `ResourceManager`
+-------------------------------------------------------
+
+The https://github.com/visa-sdk/visa-python provides a visa package that can
+conflict with :py:mod:`visa` module provided by PyVISA, which is why the
+:py:mod:`visa` module is deprecated and it is preferred to import
+:py:mod:`pyvisa` instead of :py:mod:`visa`. Both modules provides the
+same interface and no other changes should be needed.
+
+
 Error: No matching architecture
 -------------------------------
 
@@ -98,7 +108,7 @@ architecture.
 First, determine the details of your installation with the help of the
 following debug command::
 
-    python -m visa info
+    pyvisa-info
 
 You will see the 'bitness' of the Python interpreter and at the end you will
 see the list of VISA libraries that PyVISA was able to find.

docs/source/faq/getting_nivisa.rst

@@ -10,10 +10,6 @@ and then choose the Python version matching the installed NI-VISA bitness.
 PyVISA includes a debugging command to help you troubleshoot this
 (and other things)::
 
-    python -m visa info
-
-or equivalently::
-
     pyvisa-info
 
 According to National Instruments, NI VISA **17.5** is available for the

docs/source/faq/migrating.rst

@@ -24,20 +24,20 @@ Indeed PyVISA 1.6 breaks compatibility to bring across a few good things.
 
 **If you are doing:**
 
-    >>> import visa
-    >>> keithley = visa.instrument("GPIB::12")
+    >>> import pyvisa
+    >>> keithley = pyvisa.instrument("GPIB::12")
     >>> print(keithley.ask("*IDN?"))
 
 change it to:
 
-    >>> import visa
-    >>> rm = visa.ResourceManager()
+    >>> import pyvisa
+    >>> rm = pyvisa.ResourceManager()
     >>> keithley = rm.open_resource("GPIB::12")
     >>> print(keithley.query("*IDN?"))
 
 **If you are doing:**
 
-    >>> print(visa.get_instruments_list())
+    >>> print(pyvisa.get_instruments_list())
 
 change it to:
 
@@ -50,8 +50,8 @@ change it to:
 
 change it to:
 
-    >>> import visa
-    >>> rm = visa.ResourceManager("/path/to/my/libvisa.so.7")
+    >>> import pyvisa
+    >>> rm = pyvisa.ResourceManager("/path/to/my/libvisa.so.7")
     >>> lib = rm.visalib
 
 
@@ -186,9 +186,9 @@ both in ``pyvisa.highlevel``). The new classes are not singletons, at least not
 strict sense. Multiple instances of ``VisaLibrary`` and ``ResourceManager`` are possible,
 but only if they refer to different foreign libraries. In code, this means:
 
-    >>> lib1 = visa.VisaLibrary("/path/to/my/libvisa.so.7")
-    >>> lib2 = visa.VisaLibrary("/path/to/my/libvisa.so.7")
-    >>> lib3 = visa.VisaLibrary("/path/to/my/libvisa.so.8")
+    >>> lib1 = pyvisa.VisaLibrary("/path/to/my/libvisa.so.7")
+    >>> lib2 = pyvisa.VisaLibrary("/path/to/my/libvisa.so.7")
+    >>> lib3 = pyvisa.VisaLibrary("/path/to/my/libvisa.so.8")
     >>> lib1 is lib2
     True
     >>> lib1 is lib3
@@ -197,12 +197,12 @@ but only if they refer to different foreign libraries. In code, this means:
 Most of the time, you will not need access to a ``VisaLibrary`` object but to a ``ResourceManager``.
 You can do:
 
-    >>> lib = visa.VisaLibrary("/path/to/my/libvisa.so.7")
+    >>> lib = pyvisa.VisaLibrary("/path/to/my/libvisa.so.7")
     >>> rm = lib.resource_manager
 
 or equivalently:
 
-    >>> rm = visa.ResourceManager("/path/to/my/libvisa.so.7")
+    >>> rm = pyvisa.ResourceManager("/path/to/my/libvisa.so.7")
 
 .. note:: If the path for the library is not given, the path is obtained from
           the user settings file (if exists) or guessed from the OS.
@@ -224,8 +224,8 @@ In 1.5, we introduced a new ``VisaLibrary`` class (``pyvisa.highlevel``) which h
 every single low level function defined in ``ctwrapper`` as bound methods. In code,
 this means that you can do::
 
-    >>> import visa
-    >>> rm = visa.ResourceManager("/path/to/my/libvisa.so.7")
+    >>> import pyvisa
+    >>> rm = pyvisa.ResourceManager("/path/to/my/libvisa.so.7")
     >>> lib = rm.visalib
     >>> print(lib.read_stb(session))
 

docs/source/index.rst

@@ -14,8 +14,8 @@ devices independently of the interface (e.g. GPIB, RS232, USB, Ethernet). As
 an example, reading self-identification from a Keithley Multimeter with GPIB
 number 12 is as easy as three lines of Python code::
 
-    >>> import visa
-    >>> rm = visa.ResourceManager()
+    >>> import pyvisa
+    >>> rm = pyvisa.ResourceManager()
     >>> rm.list_resources()
     ('ASRL1::INSTR', 'ASRL2::INSTR', 'GPIB0::12::INSTR')
     >>> inst = rm.open_resource('GPIB0::12::INSTR')

docs/source/introduction/communication.rst

@@ -14,8 +14,8 @@ An example
 
 Let's go *in medias res* and have a look at a simple example::
 
-    >>> import visa
-    >>> rm = visa.ResourceManager()
+    >>> import pyvisa
+    >>> rm = pyvisa.ResourceManager()
     >>> rm.list_resources()
     ('ASRL1::INSTR', 'ASRL2::INSTR', 'GPIB0::14::INSTR')
     >>> my_instrument = rm.open_resource('GPIB0::14::INSTR')
@@ -24,7 +24,7 @@ Let's go *in medias res* and have a look at a simple example::
 This example already shows the two main design goals of PyVISA: preferring
 simplicity over generality, and doing it the object-oriented way.
 
-After importing ``visa``, we create a ``ResourceManager`` object. If called
+After importing ``pyvisa``, we create a ``ResourceManager`` object. If called
 without arguments, PyVISA will prefer the default backend (IVI) which tries to
 find the VISA shared library for you. If it fails it will fall back to
 pyvisa-py if installed. You can check what backend is used and the location of

docs/source/introduction/getting.rst

@@ -50,8 +50,8 @@ Testing your installation
 That's all! You can check that PyVISA is correctly installed by starting up
 python, and creating a ResourceManager:
 
-    >>> import visa
-    >>> rm = visa.ResourceManager()
+    >>> import pyvisa
+    >>> rm = pyvisa.ResourceManager()
     >>> print(rm.list_resources())
 
 If you encounter any problem, take a look at the :ref:`faq-faq`. There you will

docs/source/introduction/shell.rst

@@ -9,10 +9,6 @@ The shell, moved into PyVISA from the Lantz_ Project is a text based user
 interface to interact with instruments. You can invoke it from the
 command-line::
 
-    python -m visa shell
-
-or::
-
     pyvisa-shell
 
 that will show something the following prompt::
@@ -157,21 +153,13 @@ switch shell to use non-default backend via ``-b BACKEND`` or
 
 You can invoke::
 
-    python -m visa -b sim shell
-
-or::
-
     pyvisa-shell -b sim
 
 to use python-sim as backend instead of ni backend.
 This can be used for example for testing of python-sim configuration.
 
 You can invoke::
 
-    python -m visa -b py shell
-
-or::
-
     pyvisa-shell -b py
 
 uses python-py as backend instead of ivi backend, for situation when ivi not
@@ -183,10 +171,6 @@ PyVisa Info
 
 You can invoke it from the command-line::
 
-    python -m visa info
-
-or::
-
     pyvisa-info
 
 that will  print information to diagnose PyVISA, info about Machine, Python,

pyvisa/cmd_line_tools.py

@@ -0,0 +1,46 @@
+# -*- coding: utf-8 -*-
+"""
+    pyvisa.cmd_line_tools
+    ~~~~~~~~~~~~~~~~~~~~~
+
+    Command line tools used for debugging and testing.
+
+    This file is part of PyVISA.
+
+    :copyright: 2019 by PyVISA Authors, see AUTHORS for more details.
+    :license: MIT, see LICENSE for more details.
+"""
+
+from __future__ import division, unicode_literals, print_function, absolute_import
+
+
+
+def visa_main(command=None):
+    import argparse
+    parser = argparse.ArgumentParser(description='PyVISA command-line utilities')
+
+    parser.add_argument('--backend', '-b', dest='backend', action='store', default=None,
+                        help='backend to be used (default: ivi)')
+
+    if not command:
+        subparsers = parser.add_subparsers(title='command', dest='command')
+
+        info_parser = subparsers.add_parser('info', help='print information to diagnose PyVISA')
+
+        console_parser = subparsers.add_parser('shell', help='start the PyVISA console')
+
+    args = parser.parse_args()
+    if command:
+        args.command = command
+    if args.command == 'info':
+        from pyvisa import util
+        util.get_debug_info()
+    elif args.command == 'shell':
+        from pyvisa import shell
+        shell.main('@' + args.backend if args.backend else '')
+
+def visa_shell():
+    visa_main('shell')
+
+def visa_info():
+    visa_main('info')

pyvisa/highlevel.py

@@ -56,8 +56,8 @@ class VisaLibraryBase(object):
     is the :class:`pyvisa.highlevel.ResourceManager`. If needed, you can access the
     VISA library from it::
 
-        >>> import visa
-        >>> rm = visa.ResourceManager("/path/to/my/libvisa.so.7")
+        >>> import pyvisa
+        >>> rm = pyvisa.ResourceManager("/path/to/my/libvisa.so.7")
         >>> lib = rm.visalib
     """
 
@@ -514,6 +514,7 @@ def flush(self, session, mask):
             The following values (defined in the constants module can be
             combined using the | operator. However multiple operations on a
             single buffer cannot be combined.
+
             - VI_READ_BUF: Discard the read buffer contents and if data was
               present in the read buffer and no END-indicator was present,
               read from the device until encountering an END indicator
@@ -532,8 +533,10 @@ def flush(self, session, mask):
               data to the device.
             - VI_IO_OUT_BUF_DISCARD: Discard the transmit buffer contents (does
               not perform any I/O to the device).
+
         :return: return value of the library call.
         :rtype: :class:`pyvisa.constants.StatusCode`
+
         """
         raise NotImplementedError
 

setup.py

@@ -65,8 +65,8 @@ def read(filename):
                 'pyvisa.testsuite'],
       platforms="Linux, Windows,Mac",
       entry_points={'console_scripts':
-                    ['pyvisa-shell=visa:visa_shell',
-                     'pyvisa-info=visa:visa_info']},
+                    ['pyvisa-shell=pyvisa.cmd_line_tools:visa_shell',
+                     'pyvisa-info=pyvisa.cmd_line_tools:visa_info']},
       py_modules=['visa'],
       use_2to3=False,
       zip_safe=False)