diff --git a/README.rst b/README.rst index 1bb4b89..86110a0 100644 --- a/README.rst +++ b/README.rst @@ -46,7 +46,7 @@ for http networking. How does this library work ~~~~~~~~~~~~~~~~~~~~~~~~~~ -You may wondering why this library works properly, whereas other +You may wonder why this library works properly, whereas other approaches such like goslate won't work since Google has updated its translation service recently with a ticket mechanism to prevent a lot of crawler programs. diff --git a/docs/_themes/solar/NEWS.txt b/docs/_themes/solar/NEWS.txt new file mode 100644 index 0000000..8333abb --- /dev/null +++ b/docs/_themes/solar/NEWS.txt @@ -0,0 +1,32 @@ +News +==== + +1.3 +--- +* Release date: 2012-11-01. +* Source Code Pro is now used for code samples. +* Reduced font size of pre elements. +* Horizontal rule for header elements. +* HTML pre contents are now wrapped (no scrollbars). +* Changed permalink color from black to a lighter one. + +1.2 +--- +* Release date: 2012-10-03. +* Style additional admonition levels. +* Increase padding for navigation links (minor). +* Add shadow for admonition items (minor). + +1.1 +--- +* Release date: 2012-09-05. +* Add a new background. +* Revert font of headings to Open Sans Light. +* Darker color for h3 - h6. +* Removed dependency on solarized dark pygments style. +* Nice looking scrollbars for pre element. + +1.0 +--- +* Release date: 2012-08-24. +* Initial release. diff --git a/docs/_themes/solar/README.rst b/docs/_themes/solar/README.rst new file mode 100644 index 0000000..afd75a5 --- /dev/null +++ b/docs/_themes/solar/README.rst @@ -0,0 +1,28 @@ +Solar theme for Python Sphinx +============================= +Solar is an attempt to create a theme for Sphinx based on the `Solarized `_ color scheme. + +Preview +------- +http://vimalkumar.in/sphinx-themes/solar + +Download +-------- +Released versions are available from http://github.com/vkvn/sphinx-themes/downloads + +Installation +------------ +#. Extract the archive. +#. Modify ``conf.py`` of an existing Sphinx project or create new project using ``sphinx-quickstart``. +#. Change the ``html_theme`` parameter to ``solar``. +#. Change the ``html_theme_path`` to the location containing the extracted archive. + +License +------- +`GNU General Public License `_. + +Credits +------- +Modified from the default Sphinx theme -- Sphinxdoc + +Background pattern from http://subtlepatterns.com. diff --git a/docs/_themes/solar/layout.html b/docs/_themes/solar/layout.html new file mode 100644 index 0000000..8977d91 --- /dev/null +++ b/docs/_themes/solar/layout.html @@ -0,0 +1,34 @@ +{% extends "basic/layout.html" %} + +{%- block doctype -%} + +{%- endblock -%} + +{%- block extrahead -%} + + +{%- endblock -%} + +{# put the sidebar before the body #} +{% block sidebar1 %}{{ sidebar() }}{% endblock %} +{% block sidebar2 %} + +{% endblock %} + +{%- block footer %} +
+ {%- if show_copyright %} + {%- if hasdoc('copyright') %} + {% trans path=pathto('copyright'), copyright=copyright|e %}© Copyright {{ copyright }}.{% endtrans %} + {%- else %} + {% trans copyright=copyright|e %}© Copyright {{ copyright }}.{% endtrans %} + {%- endif %} + {%- endif %} + {%- if last_updated %} + {% trans last_updated=last_updated|e %}Last updated on {{ last_updated }}.{% endtrans %} + {%- endif %} + {%- if show_sphinx %} + {% trans sphinx_version=sphinx_version|e %}Created using Sphinx {{ sphinx_version }}.Theme by vkvn{% endtrans %} + {%- endif %} +
+{%- endblock %} diff --git a/docs/_themes/solar/static/solar.css b/docs/_themes/solar/static/solar.css new file mode 100644 index 0000000..f30cfdc --- /dev/null +++ b/docs/_themes/solar/static/solar.css @@ -0,0 +1,344 @@ +/* solar.css + * Modified from sphinxdoc.css of the sphinxdoc theme. +*/ + +@import url("basic.css"); + +/* -- page layout ----------------------------------------------------------- */ + +body { + font-family: 'Open Sans', sans-serif; + font-size: 14px; + line-height: 150%; + text-align: center; + color: #002b36; + padding: 0; + margin: 0px 80px 0px 80px; + min-width: 740px; + -moz-box-shadow: 0px 0px 10px #93a1a1; + -webkit-box-shadow: 0px 0px 10px #93a1a1; + box-shadow: 0px 0px 10px #93a1a1; + background: url("subtle_dots.png") repeat; + +} + +div.document { + background-color: #fcfcfc; + text-align: left; + background-repeat: repeat-x; +} + +div.bodywrapper { + margin: 0 240px 0 0; + border-right: 1px dotted #eee8d5; +} + +div.body { + background-color: white; + margin: 0; + padding: 0.5em 20px 20px 20px; +} + +div.related { + font-size: 1em; + background: #002b36; + color: #839496; + padding: 5px 0px; +} + +div.related ul { + height: 2em; + margin: 2px; +} + +div.related ul li { + margin: 0; + padding: 0; + height: 2em; + float: left; +} + +div.related ul li.right { + float: right; + margin-right: 5px; +} + +div.related ul li a { + margin: 0; + padding: 2px 5px; + line-height: 2em; + text-decoration: none; + color: #839496; +} + +div.related ul li a:hover { + background-color: #073642; + -webkit-border-radius: 2px; + -moz-border-radius: 2px; + border-radius: 2px; +} + +div.sphinxsidebarwrapper { + padding: 0; +} + +div.sphinxsidebar { + margin: 0; + padding: 0.5em 15px 15px 0; + width: 210px; + float: right; + font-size: 0.9em; + text-align: left; +} + +div.sphinxsidebar h3, div.sphinxsidebar h4 { + margin: 1em 0 0.5em 0; + font-size: 1em; + padding: 0.7em; + background-color: #eeeff1; +} + +div.sphinxsidebar h3 a { + color: #2E3436; +} + +div.sphinxsidebar ul { + padding-left: 1.5em; + margin-top: 7px; + padding: 0; + line-height: 150%; + color: #586e75; +} + +div.sphinxsidebar ul ul { + margin-left: 20px; +} + +div.sphinxsidebar input { + border: 1px solid #eee8d5; +} + +div.footer { + background-color: #93a1a1; + color: #eee; + padding: 3px 8px 3px 0; + clear: both; + font-size: 0.8em; + text-align: right; +} + +div.footer a { + color: #eee; + text-decoration: none; +} + +/* -- body styles ----------------------------------------------------------- */ + +p { + margin: 0.8em 0 0.5em 0; +} + +div.body a, div.sphinxsidebarwrapper a { + color: #268bd2; + text-decoration: none; +} + +div.body a:hover, div.sphinxsidebarwrapper a:hover { + border-bottom: 1px solid #268bd2; +} + +h1, h2, h3, h4, h5, h6 { + font-family: "Open Sans", sans-serif; + font-weight: 300; +} + +h1 { + margin: 0; + padding: 0.7em 0 0.3em 0; + line-height: 1.2em; + color: #002b36; + text-shadow: #eee 0.1em 0.1em 0.1em; +} + +h2 { + margin: 1.3em 0 0.2em 0; + padding: 0 0 10px 0; + color: #073642; + border-bottom: 1px solid #eee; +} + +h3 { + margin: 1em 0 -0.3em 0; + padding-bottom: 5px; +} + +h3, h4, h5, h6 { + color: #073642; + border-bottom: 1px dotted #eee; +} + +div.body h1 a, div.body h2 a, div.body h3 a, div.body h4 a, div.body h5 a, div.body h6 a { + color: #657B83!important; +} + +h1 a.anchor, h2 a.anchor, h3 a.anchor, h4 a.anchor, h5 a.anchor, h6 a.anchor { + display: none; + margin: 0 0 0 0.3em; + padding: 0 0.2em 0 0.2em; + color: #aaa!important; +} + +h1:hover a.anchor, h2:hover a.anchor, h3:hover a.anchor, h4:hover a.anchor, +h5:hover a.anchor, h6:hover a.anchor { + display: inline; +} + +h1 a.anchor:hover, h2 a.anchor:hover, h3 a.anchor:hover, h4 a.anchor:hover, +h5 a.anchor:hover, h6 a.anchor:hover { + color: #777; + background-color: #eee; +} + +a.headerlink { + color: #c60f0f!important; + font-size: 1em; + margin-left: 6px; + padding: 0 4px 0 4px; + text-decoration: none!important; +} + +a.headerlink:hover { + background-color: #ccc; + color: white!important; +} + + +cite, code, tt { + font-family: 'Source Code Pro', monospace; + font-size: 0.9em; + letter-spacing: 0.01em; + background-color: #eeeff2; + font-style: normal; +} + +hr { + border: 1px solid #eee; + margin: 2em; +} + +.highlight { + -webkit-border-radius: 2px; + -moz-border-radius: 2px; + border-radius: 2px; +} + +pre { + font-family: 'Source Code Pro', monospace; + font-style: normal; + font-size: 0.9em; + letter-spacing: 0.015em; + line-height: 120%; + padding: 0.7em; + white-space: pre-wrap; /* css-3 */ + white-space: -moz-pre-wrap; /* Mozilla, since 1999 */ + white-space: -pre-wrap; /* Opera 4-6 */ + white-space: -o-pre-wrap; /* Opera 7 */ + word-wrap: break-word; /* Internet Explorer 5.5+ */ +} + +pre a { + color: inherit; + text-decoration: underline; +} + +td.linenos pre { + padding: 0.5em 0; +} + +div.quotebar { + background-color: #f8f8f8; + max-width: 250px; + float: right; + padding: 2px 7px; + border: 1px solid #ccc; +} + +div.topic { + background-color: #f8f8f8; +} + +table { + border-collapse: collapse; + margin: 0 -0.5em 0 -0.5em; +} + +table td, table th { + padding: 0.2em 0.5em 0.2em 0.5em; +} + +div.admonition { + font-size: 0.9em; + margin: 1em 0 1em 0; + border: 1px solid #eee; + background-color: #f7f7f7; + padding: 0; + -moz-box-shadow: 0px 8px 6px -8px #93a1a1; + -webkit-box-shadow: 0px 8px 6px -8px #93a1a1; + box-shadow: 0px 8px 6px -8px #93a1a1; +} + +div.admonition p { + margin: 0.5em 1em 0.5em 1em; + padding: 0.2em; +} + +div.admonition pre { + margin: 0.4em 1em 0.4em 1em; +} + +div.admonition p.admonition-title +{ + margin: 0; + padding: 0.2em 0 0.2em 0.6em; + color: white; + border-bottom: 1px solid #eee8d5; + font-weight: bold; + background-color: #268bd2; +} + +div.warning p.admonition-title, +div.important p.admonition-title { + background-color: #cb4b16; +} + +div.hint p.admonition-title, +div.tip p.admonition-title { + background-color: #859900; +} + +div.caution p.admonition-title, +div.attention p.admonition-title, +div.danger p.admonition-title, +div.error p.admonition-title { + background-color: #dc322f; +} + +div.admonition ul, div.admonition ol { + margin: 0.1em 0.5em 0.5em 3em; + padding: 0; +} + +div.versioninfo { + margin: 1em 0 0 0; + border: 1px solid #eee; + background-color: #DDEAF0; + padding: 8px; + line-height: 1.3em; + font-size: 0.9em; +} + +div.viewcode-block:target { + background-color: #f4debf; + border-top: 1px solid #eee; + border-bottom: 1px solid #eee; +} diff --git a/docs/_themes/solar/static/solarized-dark.css b/docs/_themes/solar/static/solarized-dark.css new file mode 100644 index 0000000..6ebb945 --- /dev/null +++ b/docs/_themes/solar/static/solarized-dark.css @@ -0,0 +1,84 @@ +/* solarized dark style for solar theme */ + +/*style pre scrollbar*/ +pre::-webkit-scrollbar, .highlight::-webkit-scrollbar { + height: 0.5em; + background: #073642; +} + +pre::-webkit-scrollbar-thumb { + border-radius: 1em; + background: #93a1a1; +} + +/* pygments style */ +.highlight .hll { background-color: #ffffcc } +.highlight { background: #002B36!important; color: #93A1A1 } +.highlight .c { color: #586E75 } /* Comment */ +.highlight .err { color: #93A1A1 } /* Error */ +.highlight .g { color: #93A1A1 } /* Generic */ +.highlight .k { color: #859900 } /* Keyword */ +.highlight .l { color: #93A1A1 } /* Literal */ +.highlight .n { color: #93A1A1 } /* Name */ +.highlight .o { color: #859900 } /* Operator */ +.highlight .x { color: #CB4B16 } /* Other */ +.highlight .p { color: #93A1A1 } /* Punctuation */ +.highlight .cm { color: #586E75 } /* Comment.Multiline */ +.highlight .cp { color: #859900 } /* Comment.Preproc */ +.highlight .c1 { color: #586E75 } /* Comment.Single */ +.highlight .cs { color: #859900 } /* Comment.Special */ +.highlight .gd { color: #2AA198 } /* Generic.Deleted */ +.highlight .ge { color: #93A1A1; font-style: italic } /* Generic.Emph */ +.highlight .gr { color: #DC322F } /* Generic.Error */ +.highlight .gh { color: #CB4B16 } /* Generic.Heading */ +.highlight .gi { color: #859900 } /* Generic.Inserted */ +.highlight .go { color: #93A1A1 } /* Generic.Output */ +.highlight .gp { color: #93A1A1 } /* Generic.Prompt */ +.highlight .gs { color: #93A1A1; font-weight: bold } /* Generic.Strong */ +.highlight .gu { color: #CB4B16 } /* Generic.Subheading */ +.highlight .gt { color: #93A1A1 } /* Generic.Traceback */ +.highlight .kc { color: #CB4B16 } /* Keyword.Constant */ +.highlight .kd { color: #268BD2 } /* Keyword.Declaration */ +.highlight .kn { color: #859900 } /* Keyword.Namespace */ +.highlight .kp { color: #859900 } /* Keyword.Pseudo */ +.highlight .kr { color: #268BD2 } /* Keyword.Reserved */ +.highlight .kt { color: #DC322F } /* Keyword.Type */ +.highlight .ld { color: #93A1A1 } /* Literal.Date */ +.highlight .m { color: #2AA198 } /* Literal.Number */ +.highlight .s { color: #2AA198 } /* Literal.String */ +.highlight .na { color: #93A1A1 } /* Name.Attribute */ +.highlight .nb { color: #B58900 } /* Name.Builtin */ +.highlight .nc { color: #268BD2 } /* Name.Class */ +.highlight .no { color: #CB4B16 } /* Name.Constant */ +.highlight .nd { color: #268BD2 } /* Name.Decorator */ +.highlight .ni { color: #CB4B16 } /* Name.Entity */ +.highlight .ne { color: #CB4B16 } /* Name.Exception */ +.highlight .nf { color: #268BD2 } /* Name.Function */ +.highlight .nl { color: #93A1A1 } /* Name.Label */ +.highlight .nn { color: #93A1A1 } /* Name.Namespace */ +.highlight .nx { color: #93A1A1 } /* Name.Other */ +.highlight .py { color: #93A1A1 } /* Name.Property */ +.highlight .nt { color: #268BD2 } /* Name.Tag */ +.highlight .nv { color: #268BD2 } /* Name.Variable */ +.highlight .ow { color: #859900 } /* Operator.Word */ +.highlight .w { color: #93A1A1 } /* Text.Whitespace */ +.highlight .mf { color: #2AA198 } /* Literal.Number.Float */ +.highlight .mh { color: #2AA198 } /* Literal.Number.Hex */ +.highlight .mi { color: #2AA198 } /* Literal.Number.Integer */ +.highlight .mo { color: #2AA198 } /* Literal.Number.Oct */ +.highlight .sb { color: #586E75 } /* Literal.String.Backtick */ +.highlight .sc { color: #2AA198 } /* Literal.String.Char */ +.highlight .sd { color: #93A1A1 } /* Literal.String.Doc */ +.highlight .s2 { color: #2AA198 } /* Literal.String.Double */ +.highlight .se { color: #CB4B16 } /* Literal.String.Escape */ +.highlight .sh { color: #93A1A1 } /* Literal.String.Heredoc */ +.highlight .si { color: #2AA198 } /* Literal.String.Interpol */ +.highlight .sx { color: #2AA198 } /* Literal.String.Other */ +.highlight .sr { color: #DC322F } /* Literal.String.Regex */ +.highlight .s1 { color: #2AA198 } /* Literal.String.Single */ +.highlight .ss { color: #2AA198 } /* Literal.String.Symbol */ +.highlight .bp { color: #268BD2 } /* Name.Builtin.Pseudo */ +.highlight .vc { color: #268BD2 } /* Name.Variable.Class */ +.highlight .vg { color: #268BD2 } /* Name.Variable.Global */ +.highlight .vi { color: #268BD2 } /* Name.Variable.Instance */ +.highlight .il { color: #2AA198 } /* Literal.Number.Integer.Long */ diff --git a/docs/_themes/solar/static/subtle_dots.png b/docs/_themes/solar/static/subtle_dots.png new file mode 100644 index 0000000..bb2d611 Binary files /dev/null and b/docs/_themes/solar/static/subtle_dots.png differ diff --git a/docs/_themes/solar/theme.conf b/docs/_themes/solar/theme.conf new file mode 100644 index 0000000..d8fc2f3 --- /dev/null +++ b/docs/_themes/solar/theme.conf @@ -0,0 +1,4 @@ +[theme] +inherit = basic +stylesheet = solar.css +pygments_style = none diff --git a/docs/conf.py b/docs/conf.py index c928307..ebf14e9 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -1,7 +1,7 @@ #!/usr/bin/env python3 # -*- coding: utf-8 -*- # -# py-googletrans documentation build configuration file, created by +# Googletrans documentation build configuration file, created by # sphinx-quickstart on Fri Jun 5 17:51:30 2015. # # This file is execfile()d with the current directory set to its @@ -13,6 +13,7 @@ # All configuration values have a default; values that are commented out # serve to show the default. +import datetime import sys import os import shlex @@ -35,6 +36,7 @@ import googletrans # ones. extensions = [ 'sphinx.ext.autodoc', + 'sphinx.ext.intersphinx', # 'sphinx.ext.viewcode', ] @@ -53,8 +55,8 @@ source_suffix = '.rst' master_doc = 'index' # General information about the project. -project = 'py-googletrans' -copyright = '2015, SuHun Han (ssut)' +project = 'Googletrans' +copyright = str(datetime.date.today().year) + ', SuHun Han (ssut)' author = 'SuHun Han (ssut)' # The version info for the project you're documenting, acts as replacement for @@ -81,7 +83,7 @@ language = None # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. -exclude_patterns = ['_build'] +exclude_patterns = ['_build', '_themes'] # The reST default role (used for this markup: `text`) to use for all # documents. @@ -110,12 +112,14 @@ pygments_style = 'sphinx' # If true, `todo` and `todoList` produce output, else they produce nothing. todo_include_todos = False +suppress_warnings = ['image.nonlocal_uri'] + # -- Options for HTML output ---------------------------------------------- # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. -html_theme = 'alabaster' +html_theme = 'solar' # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the @@ -123,7 +127,7 @@ html_theme = 'alabaster' #html_theme_options = {} # Add any paths that contain custom themes here, relative to this directory. -#html_theme_path = [] +html_theme_path = ['_themes'] # The name for this set of Sphinx documents. If None, it defaults to # " v documentation". @@ -144,7 +148,7 @@ html_theme = 'alabaster' # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ['_static'] +html_static_path = [] # Add any extra paths that contain custom files (such as robots.txt or # .htaccess) here, relative to this directory. These files are copied @@ -170,13 +174,13 @@ html_static_path = ['_static'] #html_domain_indices = True # If false, no index is generated. -#html_use_index = True +html_use_index = False # If true, the index is split into individual pages for each letter. #html_split_index = False # If true, links to the reST sources are added to the pages. -#html_show_sourcelink = True +html_show_sourcelink = True # If true, "Created using Sphinx" is shown in the HTML footer. Default is True. #html_show_sphinx = True @@ -207,7 +211,7 @@ html_static_path = ['_static'] #html_search_scorer = 'scorer.js' # Output file base name for HTML help builder. -htmlhelp_basename = 'py-googletransdoc' +htmlhelp_basename = 'Googletransdoc' # -- Options for LaTeX output --------------------------------------------- @@ -229,7 +233,7 @@ latex_elements = { # (source start file, target name, title, # author, documentclass [howto, manual, or own class]). latex_documents = [ - (master_doc, 'py-googletrans.tex', 'py-googletrans Documentation', + (master_doc, 'Googletrans.tex', 'Googletrans Documentation', 'SuHun Han (ssut)', 'manual'), ] @@ -259,13 +263,15 @@ latex_documents = [ # One entry per manual page. List of tuples # (source start file, name, description, authors, manual section). man_pages = [ - (master_doc, 'py-googletrans', 'py-googletrans Documentation', + (master_doc, 'Googletrans', 'Googletrans Documentation', [author], 1) ] # If true, show URL addresses after external links. #man_show_urls = False +intersphinx_mapping = {'http://docs.python.org/': None} + # -- Options for Texinfo output ------------------------------------------- @@ -273,8 +279,8 @@ man_pages = [ # (source start file, target name, title, author, # dir menu entry, description, category) texinfo_documents = [ - (master_doc, 'py-googletrans', 'py-googletrans Documentation', - author, 'py-googletrans', 'One line description of project.', + (master_doc, 'Googletrans', 'Googletrans Documentation', + author, 'Googletrans', 'One line description of project.', 'Miscellaneous'), ] @@ -289,3 +295,5 @@ texinfo_documents = [ # If true, do not generate a @detailmenu in the "Top" node's menu. #texinfo_no_detailmenu = False + +autodoc_member_order = 'bysource' \ No newline at end of file diff --git a/docs/googletrans.rst b/docs/googletrans.rst deleted file mode 100644 index 9c51c90..0000000 --- a/docs/googletrans.rst +++ /dev/null @@ -1,46 +0,0 @@ -googletrans package -=================== - -Submodules ----------- - -googletrans.conversion module ------------------------------ - -.. automodule:: googletrans.conversion - :members: - :undoc-members: - :show-inheritance: - -googletrans.response module ---------------------------- - -.. automodule:: googletrans.response - :members: - :undoc-members: - :show-inheritance: - -googletrans.translator module ------------------------------ - -.. automodule:: googletrans.translator - :members: - :undoc-members: - :show-inheritance: - -googletrans.urls module ------------------------ - -.. automodule:: googletrans.urls - :members: - :undoc-members: - :show-inheritance: - - -Module contents ---------------- - -.. automodule:: googletrans - :members: - :undoc-members: - :show-inheritance: diff --git a/docs/index.rst b/docs/index.rst index e260e0b..42ffe04 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,22 +1,188 @@ -.. py-googletrans documentation master file, created by - sphinx-quickstart on Fri Jun 5 17:51:30 2015. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. +=============================================================== +Googletrans: Free and Unlimited Google translate API for Python +=============================================================== -Welcome to py-googletrans's documentation! -========================================== +.. image:: https://img.shields.io/github/license/mashape/apistatus.svg + :target: http://opensource.org/licenses/MIT +.. image:: https://travis-ci.org/ssut/py-googletrans.svg?branch=master + :target: https://travis-ci.org/ssut/py-googletrans +.. image:: https://readthedocs.org/projects/py-googletrans/badge/?version=latest + :target: https://readthedocs.org/projects/py-googletrans/?badge=latest +.. image:: https://badge.fury.io/py/googletrans.svg + :target: http://badge.fury.io/py/googletrans +.. image:: https://coveralls.io/repos/github/ssut/py-googletrans/badge.svg + :target: https://coveralls.io/github/ssut/py-googletrans +.. image:: https://codeclimate.com/github/ssut/py-googletrans/badges/gpa.svg + :target: https://codeclimate.com/github/ssut/py-googletrans -Contents: +Googletrans is a **free** and **unlimited** python library that +implemented Google Translate API. This uses the `Google Translate Ajax +API `__ to make calls to such methods as +detect and translate. -.. toctree:: - :maxdepth: 2 +-------- +Features +-------- + +- Fast and reliable - it uses the same servers that + translate.google.com uses +- Auto language detection +- Bulk translations +- Customizable service URL +- Connection pooling (the advantage of using requests.Session) +- HTTP/2 support + +~~~~~~~~~~~~~~~~~~~~~ +Note on library usage +~~~~~~~~~~~~~~~~~~~~~ + +- The maximum character limit on a single text is 15k. + +- Due to limitations of the web version of google translate, this API + does not guarantee that the library would work properly at all times. + (so please use this library if you don't care about stability.) + +- If you want to use a stable API, I highly recommend you to use + `Google's official translate + API `__. + +- If you get HTTP 5xx error or errors like #6, it's probably because + Google has banned your client IP address. + +---------- +Quickstart +---------- + +You can install it from PyPI_: + +.. sourcecode:: bash + + $ pip install googletrans + +.. _PyPI: https://pypi.python.org/pypi/googletrans + +~~~~~~~~~~~~~~ +HTTP/2 support +~~~~~~~~~~~~~~ + +This is a great deal for everyone! (up to 2x times faster in my test) If +you want to get googletrans faster you should install +`hyper `__ package. Googletrans will +automatically detect if hyper is installed and if so, it will be used +for http networking. + +~~~~~~~~~~~ +Basic Usage +~~~~~~~~~~~ + +If source language is not given, google translate attempts to detect the +source language. + +.. code-block:: python + + >>> from googletrans import Translator + >>> translator = Translator() + >>> translator.translate('안녕하세요.') + # + + >>> translator.translate('안녕하세요.', dest='ja') + # + + >>> translator.translate('veritas lux mea', src='la') + # + +~~~~~~~~~~~~~~~~~~~~~ +Customize service URL +~~~~~~~~~~~~~~~~~~~~~ + +You can use another google translate domain for translation. If multiple +URLs are provided it then randomly chooses a domain. + +.. code:: python + + >>> from googletrans import Translator + >>> translator = Translator(service_urls=[ + 'translate.google.com', + 'translate.google.co.kr', + ]) + +~~~~~~~~~~~~~~~~~~~~~ +Advanced Usage (Bulk) +~~~~~~~~~~~~~~~~~~~~~ + +Array can be used to translate a batch of strings in a single method +call and a single HTTP session. The exact same method shown above work +for arrays as well. + +.. code:: python + + >>> translations = translator.translate(['The quick brown fox', 'jumps over', 'the lazy dog'], dest='ko') + >>> for translation in translations: + ... print(translation.origin, ' -> ', translation.text) + # The quick brown fox -> 빠른 갈색 여우 + # jumps over -> 이상 점프 + # the lazy dog -> 게으른 개 + +~~~~~~~~~~~~~~~~~~ +Language detection +~~~~~~~~~~~~~~~~~~ + +The detect method, as its name implies, identifies the language used in +a given sentence. + +.. code:: python + + >>> translator.detect('이 문장은 한글로 쓰여졌습니다.') + # + >>> translator.detect('この文章は日本語で書かれました。') + # + >>> translator.detect('This sentence is written in English.') + # + >>> translator.detect('Tiu frazo estas skribita en Esperanto.') + # + +--------- +API Guide +--------- +====================== +googletrans.Translator +====================== -Indices and tables +.. autoclass:: googletrans.Translator + :members: + +================== +googletrans.models ================== -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` +.. automodule:: googletrans.models + :members: +================== +googletrans.gtoken +================== + +.. hint:: + + This is for internal use only to generate a valid token to access + translate.google.com ajax API. + +.. automodule:: googletrans.gtoken + :members: + +===================== +googletrans.LANGUAGES +===================== + +.. hint:: + + iso639-1 language codes for + `supported languages `_ + for translation. Some language codes also include a country code, like zh-CN or zh-TW. + +.. literalinclude:: ../googletrans/constants.py + :language: python + :lines: 7- + :linenos: \ No newline at end of file diff --git a/docs/modules.rst b/docs/modules.rst deleted file mode 100644 index e2ad7d4..0000000 --- a/docs/modules.rst +++ /dev/null @@ -1,9 +0,0 @@ -. -= - -.. toctree:: - :maxdepth: 4 - - googletrans - setup - tests diff --git a/docs/setup.rst b/docs/setup.rst deleted file mode 100644 index 31789b1..0000000 --- a/docs/setup.rst +++ /dev/null @@ -1,7 +0,0 @@ -setup module -============ - -.. automodule:: setup - :members: - :undoc-members: - :show-inheritance: diff --git a/docs/tests.rst b/docs/tests.rst deleted file mode 100644 index 03031c4..0000000 --- a/docs/tests.rst +++ /dev/null @@ -1,7 +0,0 @@ -tests module -============ - -.. automodule:: tests - :members: - :undoc-members: - :show-inheritance: diff --git a/googletrans/__init__.py b/googletrans/__init__.py index b66a4ea..94db891 100644 --- a/googletrans/__init__.py +++ b/googletrans/__init__.py @@ -4,4 +4,5 @@ __version_info__ = 2, 0, 0 __version__ = '.'.join(str(v) for v in __version_info__) -from googletrans.client import Translator \ No newline at end of file +from googletrans.client import Translator +from googletrans.constants import LANGUAGES \ No newline at end of file diff --git a/googletrans/client.py b/googletrans/client.py index 060437a..79a9a66 100644 --- a/googletrans/client.py +++ b/googletrans/client.py @@ -18,6 +18,17 @@ EXCLUDES = ('en', 'ca', 'fr') class Translator(object): + """Google Translate ajax API implementation class + + You have to create an instance of Translator to use this API + + :param service_urls: google translate url list. URLs will be used randomly. + For example ``['translate.google.com', 'translate.google.co.kr']`` + :type service_urls: a sequence of strings + + :param user_agent: the User-Agent header to send when making requests. + :type user_agent: :class:`str` + """ def __init__(self, service_urls=None, user_agent=DEFAULT_USER_AGENT): self.session = requests.Session() @@ -65,8 +76,23 @@ class Translator(object): return data def translate(self, text, dest='en', src='auto'): - """ - Translate the passed text into destination language. + """Translate text from source language to destination language + + :param text: The source text(s) to be translated. Batch translation is supported via sequence input. + :type text: UTF-8 :class:`str`; :class:`unicode`; string sequence (list, tuple, iterator, generator) + + :param dest: The language to translate the source text into. + The value should be one of the language codes listed in :const:`googletrans.LANGUAGES`. + :param dest: :class:`str`; :class:`unicode` + + :param src: The language of the source text. + The value should be one of the language codes listed in :const:`googletrans.LANGUAGES`. + If a language is not specified, + the system will attempt to identify the source language automatically. + :param src: :class:`str`; :class:`unicode` + + :rtype: Translated + :rtype: :class:`list` (when a list is passed) Basic usage: >>> from googletrans import Translator @@ -85,14 +111,6 @@ class Translator(object): The quick brown fox -> 빠른 갈색 여우 jumps over -> 이상 점프 the lazy dog -> 게으른 개 - - :param text: the text you want to translate. - you can pass this parameter as a list object, as shown in the advanced usage above. - :param dest: the destination language you want to translate. (default: en) - :param src: the source language you want to translate. (default: auto) - - :rtype: Translated - :rtype: list (when list is passed) """ if isinstance(text, list): result = [] @@ -140,8 +158,14 @@ class Translator(object): return result def detect(self, text): - """ - Detect the language of a text. + """Detect language of the input text + + :param text: The source text(s) whose language you want to identify. + Batch detection is supported via sequence input. + :type text: UTF-8 :class:`str`; :class:`unicode`; string sequence (list, tuple, iterator, generator) + + :rtype: Detected + :rtype: :class:`list` (when a list is passed) Basic usage: >>> from googletrans import Translator @@ -163,11 +187,6 @@ class Translator(object): ja 0.92929292 en 0.96954316 fr 0.043500196 - - :param text: the text you want to detect. - - :rtype: Detected - :rtype: list (when list is passed) """ if isinstance(text, list): result = [] diff --git a/googletrans/gtoken.py b/googletrans/gtoken.py index b651044..cfa4d50 100644 --- a/googletrans/gtoken.py +++ b/googletrans/gtoken.py @@ -29,13 +29,12 @@ class TokenAcquirer(object): This operation will cause an additional request to get an initial token from translate.google.com. - :Example: - - >>> from gtoken import TokenAcquirer + Example usage: + >>> from googletrans.gtoken import TokenAcquirer >>> acquirer = TokenAcquirer() >>> text = 'test' >>> tk = acquirer.do(text) - >>> print(tk) + >>> tk 950629.577246 """ diff --git a/googletrans/models.py b/googletrans/models.py index 3df5647..043af28 100644 --- a/googletrans/models.py +++ b/googletrans/models.py @@ -1,12 +1,11 @@ class Translated(object): - """ - The Translated object, which contains Google Translator's result. + """Translate result object :param src: source langauge (default: auto) :param dest: destination language (default: en) :param origin: original text :param text: translated text - :param pronunciation: the pronunciation provided by Google Translator + :param pronunciation: pronunciation """ def __init__(self, src, dest, origin, text, pronunciation): self.src = src @@ -19,16 +18,15 @@ class Translated(object): return self.__unicode__() def __unicode__(self): # pragma: nocover - return u''.format( + return u'Translated(src={src}, dest={dest}, text={text}, pronunciation={pronunciation})'.format( src=self.src, dest=self.dest, text=self.text, pronunciation=self.pronunciation) class Detected(object): - """ - The detected object, which contains Google Translator's langauge detection result. + """Language detection result object :param lang: detected language - :param confidence: the confidence of detection (0.00 to 1.00) + :param confidence: the confidence of detection result (0.00 to 1.00) """ def __init__(self, lang, confidence): self.lang = lang @@ -38,5 +36,5 @@ class Detected(object): return self.__unicode__() def __unicode__(self): # pragma: nocover - return u''.format( + return u'Detected(lang={lang}, confidence={confidence})'.format( lang=self.lang, confidence=self.confidence) \ No newline at end of file