Metadata-Version: 2.1
Name: ts3
Version: 2.0.0b2
Summary: TS3 Server Query API and TS3 Client Query API
Home-page: https://github.com/benediktschmitt/py-ts3
Author: The py-ts3 authors <see AUTHORS.txt>
Author-email: UNKNOWN
License: not available
Download-URL: https://github.com/benediktschmitt/Py-TS3/archive/master.zip
Platform: UNKNOWN
Classifier: License :: OSI Approved :: MIT License
Classifier: Development Status :: 4 - Beta
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Communications
Classifier: Topic :: Internet
Classifier: Topic :: Software Development :: Libraries
Requires-Dist: paramiko

PyTS3
=====

`Installation <#installation>`_
~ `TS3 Server Whitelist <#ts3-server-whitelist>`_
~ `Introduction <#introduction>`_
~ `Examples <#examples>`_
~ `Changelog <https://py-ts3.readthedocs.io/en/v2/changelog.html>`_
~ `Bugs <#bugs>`_
~ `License <#license>`_

**>> Click** `here <https://py-ts3.readthedocs.io/en/v2/changelog.html>`_ **to find out what's new in version 2.0.0. <<**

This package provides a **Python 3 API** for

* TS3 query connections,
* TS3 query events,
* TS3 file transfers,
* the TS3 client query interface,
* and TS3 client events.

You can find a complete API documentation
`here <http://py-ts3.readthedocs.io/en/v2/>`_.

.. code-block:: python

	import ts3

	# Change the URI scheme from *ssh* to *telnet*, if your server does not
	# support ssh.
	with ts3.query.TS3ServerConnection("ssh://serveradmin:Z0YxRb7u@localhost:10022") as ts3conn:
		# use sid=1
		ts3conn.exec_("use", sid=1)

		# clientlist -away -uid
		clients = ts3conn.query("clientlist", "away", "uid").all()

Installation
------------

This package is registered on PyPi, so you're done with:

.. code-block:: bash

	$ pip3 install ts3

TS3 Server Whitelist
--------------------

If you want to send lots of queries to the TS3 server, make sure, that you're
connection is not closed by the **anti-flood protection** of the TS3 server.
So it may be wise to add the host that runs the TS3 queries to the
``query_ip_whitelist.txt`` of your TS3 server:

.. code-block:: bash

	$ echo "192.168.178.42" >> path/to/ts3/server/directory/query_ip_whitelist.txt

Introduction
------------

The easiest way to get to grips with this library is taking a look at the
`examples <https://github.com/benediktschmitt/py-ts3/tree/master/ts3/examples>`_ or
simply read through the small ones in this README.

If you need information about the possible query commands, take a look at the
**TS3 Server Query Manual**, which comes as a html file in the server installation
folder, or at the **TS3 Client Query Manual** which is located in the client
installation folder.

TS3 Query Commands
''''''''''''''''''
(Excerpt from the manual)

Query commands are made up of a command word, options and parameters (key-value pairs):

.. code-block:: raw

	command key1=value1 key2=value2 key3=value3 -option1 -option1

This syntax translates into *py-ts3* as follows:

.. code-block:: python

	ts3conn.exec_("command", "option1", "option2", key1=value1, key2=value2)
	ts3conn.query("command", "option1", "option2", key1=value1, key2=value2).fetch()

The *exec()* method executes the command immediately and is often sufficient,
while the *query()* method offers a slightly more sophisticated interface and
supports pipelining:

.. code-block:: python

	# clientkick reasonid=5 reasonmsg=Go\saway! clid=1|clid=2|clid=3
	resp = ts3conn.query("clientkick", reasonid=5, reasonmsg="Go away!")\
		.pipe(clid=1).pipe(clid=2).pipe(clid=3).fetch()

	# channellist -flags -icon
	resp = ts3conn.query("channellist", "flags", "icon").fetch()
	resp = ts3conn.query("channellist").options("flags", "icon").all()
	resp = ts3conn.query("channellist").options("flags", "icon").first()

As a general rule of thumb, use *exec_()* if you don't need pipelining.

Examples
''''''''

You can find more examples in the ``ts3.examples`` package.

*	Show all clients on the virtual server with the server id 1:

	.. code-block:: python

		#!/usr/bin/python3

		import ts3

		with ts3.query.TS3ServerConnection("telnet://serveradmin:Z0YxRb7u@localhost:10011") as ts3conn:
			ts3conn.exec_("use", sid=1)

			# exec_() returns a **TS3QueryResponse** instance with the response.
			resp = ts3conn.exec_("clientlist")
			print("Clients on the server:", resp.parsed)
			print("Error:", resp.error["id"], resp.error["msg"])

			# Note, the TS3Response class and therefore the TS3QueryResponse
			# class too, can work as a rudimentary container. So, these two
			# commands are equal:
			for client in resp.parsed:
				print(client)
			for client in resp:
				print(client)

*	Say hello to all clients:

	.. code-block:: python

		#!/usr/bin/python3

		import ts3

		with ts3.query.TS3ServerConnection("telnet://serveradmin:Z0YxRb7u@localhost:10011") as ts3conn:
			ts3conn.exec_("use", sid=1)

			for client in ts3conn.exec_("clientlist"):
				msg = "Hi {}".format(client["client_nickname"])
				ts3conn.exec_("clientpoke", clid=client["clid"], msg=msg)

*	Event handling (*Server Query*):

	.. code-block:: python

		#!/usr/bin/python3

		import time
		import ts3

		with ts3.query.TS3ServerConnection("telnet://serveradmin:Z0YxRb7u@localhost:10011") as ts3conn:
			ts3conn.exec_("use", sid=1)

			# Register for events
			ts3conn.exec_("servernotifyregister", event="server")

			while True:
				ts3conn.send_keepalive()

				try:
					event = ts3conn.wait_for_event(timeout=60)
				except ts3.query.TS3TimeoutError:
					pass
				else:
					# Greet new clients.
					if event[0]["reasonid"] == "0":
						print("client connected")
						ts3conn.exec_("clientpoke", clid=event[0]["clid"], msg="Hello :)")

*	A simple TS3 viewer:

	.. code-block:: python

		#!/usr/bin/python3

		import ts3

		# The examples package already contains this implementation.
		# Note, that the examples.viewer module has an helpful class to
		# build a complete channel tree of a virtual server: ChannelTreeNode
		#
		# You may have to download it from GitHub first.
		from ts3_examples.viewer import view

		with ts3.query.TS3ServerConnection("telnet://serveradmin:Z0YxRb7u@localhost:10011") as ts3conn:
			view(ts3conn, sid=1)

*	Download and upload files:

	.. code-block:: python

		#!/usr/bin/python3

		import ts3

		with ts3.query.TS3ServerConnection("telnet://serveradmin:Z0YxRb7u@localhost:10011") as ts3conn:
			ts3conn.exec_("use", sid=1)

			# Create a new TS3FileTransfer instance associated with the
			# TS3ServerConnection.
			ts3ft = ts3.filetransfer.TS3FileTransfer(ts3conn)

			# Upload the image *baz.png* to the channel with the id 2 on the
			# TS3 server.
			# Note the opening mode ("rb").
			with open("baz.png", "rb") as file:
				ts3ft.init_upload(input_file=file, name="/baz.png", cid=2)

			# Download the file into *baz1.png*.
			with open("baz1.png", "wb") as file:
				ts3ft.init_download(output_file=file, name="/baz.png", cid=2)

*	Event handling (*Client Query*):

	.. code-block:: python

		#!/usr/bin/python3

		import time
		import ts3

		with ts3.query.TS3ServerConnection("telnet://localhost:25639") as ts3conn:
			ts3conn.exec_("auth", apikey="AAAA-....-EEEE")

			# Register for events
			ts3conn.exec_("clientnotifyregister", event="any", schandlerid=0)

			while True:
				event = ts3conn.wait_for_event()
				print(event.parsed)

Bugs
----

If you found a bug please report it or sent a pull request.

Please report grammar or spelling errors too.

Versioning
----------

For the version numbers, take a look at http://semver.org/.

License
-------

This package is licensed under the MIT License.


