<commit_before>
.. Copyright SAS Institute

******************************
Installation and configuration
******************************

=============
Installation
=============

This package installs just like any other Python package.
It is a pure Python package and works with Python 3.x
installations.  To install the latest version using `pip`, you execute the following::

    pip install saspy

or, for a specific release::

    pip install http://github.com/sassoftware/saspy/releases/saspy-X.X.X.tar.gz


To use this module after installation, you need to edit the sascfg.py file to 
configure it to be able to connect and start a SAS session. Follow the 
instructions in the next section.

* If you run into any problems, see :doc:`troubleshooting`.
* If you have questions, open an issue at https://github.com/sassoftware/saspy/issues.



===============
Configuration
===============

This module can connect and start different kinds of SAS sessions. It can connect to SAS 
on Unix, Mainframe, and Windows. It can connect to a local SAS session or remote session.
Because of the wide range of connection types, there are a number of different access methods
which are used to connect to different kinds of SAS sessions.

The current set of connection methods are as follows:

`STDIO`_
  This connection method is available on the Linux platform only. This 
  method enables you to connect to SAS on the same host as your Python process.

`STDIO over SSH`_
  This connection method is also available on the Linux platform only. This
  method can connect to SAS that is installed on a remote host, if you have passwordless
  SSH configured for your Linux user account.

`IOM`_
  The integrated object method (IOM) connection method supports SAS on any platform.
  This method can make a local Windows connection and it is also the way to connect 
  to SAS Grid through SAS Grid Manager. This method can connect to a SAS Workspace
  Server on any supported SAS platform.

Though there are several connection methods available, a single configuration file
is used to enable all the connection methods. The file contains instructions and
examples, but this section goes into more detail to explain how to configure each
type of connection.

Depending upon how you did your installation, the sascfg.py file may be in different 
locations on the file system:

* In a regular pip install, it is under the site-packages directory in the Python 
  installation. 
* If you cloned the repo or downloaded and extraced the repo and then installed, 
  it may use the sascfg.py file from that location and not copy it to site-packages.
 
First, make sure that you update the sascfg.py file that Python uses. If you are 
familiar with pip and Git, then you probably know where to look. If you are not
familiar with those tools, then there is a very simple way to determine the location
that Python is using to get at this module.

After installing, start Python and ``import saspy``. Then, simply submit 
``saspy.SAScfg``. Python will show you where it found the module. Edit that one.

.. code-block:: ipython3

    # this is an example of a repo install on Windows:

    C:\>python
    Python 3.6.0 |Anaconda custom (64-bit)| (default, Dec 23 2016, 11:57:41) [MSC v.1900 64 bit (AMD64)] on win32
    Type "help", "copyright", "credits" or "license" for more information.
    >>> import saspy
    >>> saspy.SAScfg
    <module 'saspy.sascfg' from 'E:\\metis-master\\saspy_pip\\saspy\\sascfg.py'>
    >>>

    # this is an example of a repo install on Linux:

    Linux-1> python3.5
    Python 3.5.1 (default, Jan 19 2016, 21:32:20)
    [GCC 4.4.7 20120313 (Red Hat 4.4.7-16)] on linux
    Type "help", "copyright", "credits" or "license" for more information.
    >>> import saspy
    >>> saspy.SAScfg
    <module 'saspy.sascfg' from '/opt/tom/gitlab/metis/saspy_pip/saspy/sascfg.py'>
    >>>
    
    # this is an example of a PyPi install on Linux into site-packages:

    Linux-1> python3.5
    Python 3.5.1 (default, Jan 19 2016, 21:32:20)
    [GCC 4.4.7 20120313 (Red Hat 4.4.7-16)] on linux
    Type "help", "copyright", "credits" or "license" for more information.
    >>> import saspy
    >>> saspy.SAScfg
    <module 'saspy.sascfg' from '/usr/lib/python3.5/site-packages/saspy/sascfg.py'>
    >>>
    

sascfg_personal.py
==================

Since the saspy.cfg file is in the saspy repo, as an example configuration file, it can be updated
on occasion and when you do an upgrade it will pull down the repo sascfg.py and replace the one
you've configured for your site. That means you would need to keep a copy elsewhere and then replace
the new one with your copy after upgrading or pulling, if yours was replaced. 

There is a simple solution to this. Your configurations can be in a file named sascfg_personal.py.
This file doesn't exist in the repo, so it will never be overwritten when you upgrade or pull.
saspy will always try to import sascfg_personal.py first, and only if that fails will it try to
import sascfg.py.

So copy sascfg.py to sascfg_personal.py and put all of your specific configuration into the _personal
file. Then you won't have to worry about sascfg.py getting clobbered when you pull or upgrade.

Also, everything in this doc applies to the _personal version; it's the same, just a version of the file
that will be used if it exists instead of the original one, but it won't get overwritten.
        <commit_msg>add note about cfg and pythonpath<commit_after>
.. Copyright SAS Institute

******************************
Installation and configuration
******************************

=============
Installation
=============

This package installs just like any other Python package.
It is a pure Python package and works with Python 3.x
installations.  To install the latest version using `pip`, you execute the following::

    pip install saspy

or, for a specific release::

    pip install http://github.com/sassoftware/saspy/releases/saspy-X.X.X.tar.gz


To use this module after installation, you need to edit the sascfg.py file to 
configure it to be able to connect and start a SAS session. Follow the 
instructions in the next section.

* If you run into any problems, see :doc:`troubleshooting`.
* If you have questions, open an issue at https://github.com/sassoftware/saspy/issues.



===============
Configuration
===============

This module can connect and start different kinds of SAS sessions. It can connect to SAS 
on Unix, Mainframe, and Windows. It can connect to a local SAS session or remote session.
Because of the wide range of connection types, there are a number of different access methods
which are used to connect to different kinds of SAS sessions.

The current set of connection methods are as follows:

`STDIO`_
  This connection method is available on the Linux platform only. This 
  method enables you to connect to SAS on the same host as your Python process.

`STDIO over SSH`_
  This connection method is also available on the Linux platform only. This
  method can connect to SAS that is installed on a remote host, if you have passwordless
  SSH configured for your Linux user account.

`IOM`_
  The integrated object method (IOM) connection method supports SAS on any platform.
  This method can make a local Windows connection and it is also the way to connect 
  to SAS Grid through SAS Grid Manager. This method can connect to a SAS Workspace
  Server on any supported SAS platform.

Though there are several connection methods available, a single configuration file
is used to enable all the connection methods. The file contains instructions and
examples, but this section goes into more detail to explain how to configure each
type of connection.

Depending upon how you did your installation, the sascfg.py file may be in different 
locations on the file system:

* In a regular pip install, it is under the site-packages directory in the Python 
  installation. 
* If you cloned the repo or downloaded and extraced the repo and then installed, 
  it may use the sascfg.py file from that location and not copy it to site-packages.
 
First, make sure that you update the sascfg.py file that Python uses. If you are 
familiar with pip and Git, then you probably know where to look. If you are not
familiar with those tools, then there is a very simple way to determine the location
that Python is using to get at this module.

After installing, start Python and ``import saspy``. Then, simply submit 
``saspy.SAScfg``. Python will show you where it found the module. Edit that one.

.. code-block:: ipython3

    # this is an example of a repo install on Windows:

    C:\>python
    Python 3.6.0 |Anaconda custom (64-bit)| (default, Dec 23 2016, 11:57:41) [MSC v.1900 64 bit (AMD64)] on win32
    Type "help", "copyright", "credits" or "license" for more information.
    >>> import saspy
    >>> saspy.SAScfg
    <module 'saspy.sascfg' from 'E:\\metis-master\\saspy_pip\\saspy\\sascfg.py'>
    >>>

    # this is an example of a repo install on Linux:

    Linux-1> python3.5
    Python 3.5.1 (default, Jan 19 2016, 21:32:20)
    [GCC 4.4.7 20120313 (Red Hat 4.4.7-16)] on linux
    Type "help", "copyright", "credits" or "license" for more information.
    >>> import saspy
    >>> saspy.SAScfg
    <module 'saspy.sascfg' from '/opt/tom/gitlab/metis/saspy_pip/saspy/sascfg.py'>
    >>>
    
    # this is an example of a PyPi install on Linux into site-packages:

    Linux-1> python3.5
    Python 3.5.1 (default, Jan 19 2016, 21:32:20)
    [GCC 4.4.7 20120313 (Red Hat 4.4.7-16)] on linux
    Type "help", "copyright", "credits" or "license" for more information.
    >>> import saspy
    >>> saspy.SAScfg
    <module 'saspy.sascfg' from '/usr/lib/python3.5/site-packages/saspy/sascfg.py'>
    >>>
    

sascfg_personal.py
==================

Since the saspy.cfg file is in the saspy repo, as an example configuration file, it can be updated
on occasion and when you do an upgrade it will pull down the repo sascfg.py and replace the one
you've configured for your site. That means you would need to keep a copy elsewhere and then replace
the new one with your copy after upgrading or pulling, if yours was replaced. 

There is a simple solution to this. Your configurations can be in a file named sascfg_personal.py.
This file doesn't exist in the repo, so it will never be overwritten when you upgrade or pull.
saspy will always try to import sascfg_personal.py first, and only if that fails will it try to
import sascfg.py.

So copy sascfg.py to sascfg_personal.py and put all of your specific configuration into the _personal
file. Then you won't have to worry about sascfg.py getting clobbered when you pull or upgrade.

Also, everything in this doc applies to the _personal version; it's the same, just a version of the file
that will be used if it exists instead of the original one, but it won't get overwritten.

Also note that this file does not have to live in the repo itself. It can be anywhere on the filesystem
al long as that location is in the python search path. The python search path can be found by looking
at the PYTHONPATH environment variable (if it's set), but more definitively by submitting the following:

.. code-block:: ipython3

    import sys
    sys.path

        
{'fraction_non_alphanumeric': 0.08324468085106383, 'fraction_numerical': 0.017641843971631207, 'mean_word_length': 3.7200836820083683, 'pattern_counts': {'":': 0, '<': 9, '<?xml version=': 0, '>': 69, 'https://': 2, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3193875', 'n_tokens_mistral': 3352, 'n_tokens_neox': 3097, 'n_words': 1648}