Merge pull request #30 from odesk/v0.5.6

version 0.5.6

Author: mnovozhylov

.travis.yml

@@ -0,0 +1,15 @@
+language: python
+
+python:
+  - "2.6"
+  - "2.7"
+
+install: "pip install -r requirements.py"
+
+script: nosetests
+
+notifications:
+  email:
+    recipients:
+      - apisupport@odesk.com
+    on_failure: change

changelog.rst

@@ -5,6 +5,17 @@
 Changelog
 ***************
 
+.. _0.5.6:
+
+Version 0.5.6
+-------------
+* Added new API call - :py:meth:`List categories (v2) <odesk.routers.provider.Provider_V2.get_categories_metadata>`.
+* Added new API call - :py:meth:`Get Work Diary by Contract <odesk.routers.team.Team_V2.get_workdiaries_by_contract>`.
+* Recent changes from API Changelog - Wednesday, 2015-01-12
+* Recent changes from API Changelog - Wednesday, 2014-12-03
+* Recent changes from API Changelog - Friday, 2014-11-21
+* Recent changes from API Changelog - Friday, 2014-10-31
+
 .. _0.5.5:
 
 Version 0.5.5.1

odesk/routers/hr.py

@@ -175,8 +175,7 @@ def get_company_users(self, company_referece, active=True):
     """team api"""
 
     def post_team_adjustment(self, team_reference, engagement_reference,
-                             comments, amount=None, charge_amount=None,
-                             notes=None):
+                             comments, charge_amount, notes=None):
         """
         Add bonus to an engagement.
 
@@ -188,11 +187,7 @@ def post_team_adjustment(self, team_reference, engagement_reference,
           :comments:              Comments about this adjustment, e.g.
                                  "Bonus for a good job"
 
-          :amount:                (conditionally optional) The amount that
-                                  the provider should receive, e.g. 100
-
-          :charge_amount:         (conditionally optional) The amount that
-                                  will be charged to the employer, e.g. 110
+          :charge_amount:         The amount that will be charged to the employer, e.g. 110
 
           :notes:                 (optional) Notes
 
@@ -206,17 +201,11 @@ def post_team_adjustment(self, team_reference, engagement_reference,
 
         data['engagement__reference'] = engagement_reference
         data['comments'] = comments
+        
+        if charge_amount is None or charge_amount == 0:
+            raise ApiValueError('Missed obligatory parameter ``charge_amount``')
 
-        if (amount and charge_amount) or (amount is None and
-                                          charge_amount is None):
-            raise ApiValueError('Either only one of the parameters ``amount``'
-                                ' or ``charge_amount`` should be specified')
-
-        if amount:
-            data['amount'] = amount
-
-        if charge_amount:
-            data['charge_amount'] = charge_amount
+        data['charge_amount'] = charge_amount
 
         if notes:
             data['notes'] = notes
@@ -350,8 +339,8 @@ def get_job(self, job_reference):
         return result.get('job', result)
 
     def post_job(self, buyer_team_reference, title, job_type, description,
-                 visibility, category, subcategory, budget=None, duration=None,
-                 start_date=None, end_date=None, skills=None):
+                 visibility, category=None, subcategory=None, budget=None, duration=None,
+                 start_date=None, skills=None, subcategory2=None):
         """
         Post a job.
 
@@ -382,10 +371,10 @@ def post_job(self, buyer_team_reference, title, job_type, description,
                                        where the buyer wants to control
                                        the potential applicants
 
-          :category:               The category of job, e.g. 'Web Development'
+          :category:               (conditionally optional) The category of job, e.g. 'Web Development'
                                    (where to get? - see Metadata API)
 
-          :subcategory:            The subcategory of job, e.g.
+          :subcategory:            (conditionally optional) The subcategory of job, e.g.
                                    'Web Programming'
                                    (where to get? - see Metadata API)
 
@@ -402,14 +391,14 @@ def post_job(self, buyer_team_reference, title, job_type, description,
                                    included the job will default to
                                    starting immediately.
 
-          :end_date:               (deprecated) This parameter remains
-                                   for compatibility reasons and
-                                   will be removed in future.
-
           :skills:                 (optional) Skills required for the job.
                                    Must be a list or tuple even of one item,
                                    e.g. ``['python']``
 
+          :subcategory2:           (conditionally optional) The subcategory (V2) of job, e.g.
+                                   'Web & Mobile Programming'
+                                   (where to get? - see Metadata API, List Categories (V2))
+
         """
         url = 'jobs'
         data = {}
@@ -425,8 +414,17 @@ def post_job(self, buyer_team_reference, title, job_type, description,
         assert_parameter('visibility', visibility, self.JOB_VISIBILITY_OPTIONS)
         data['visibility'] = visibility
 
-        data['category'] = category
-        data['subcategory'] = subcategory
+        if (category is None or subcategory is None) and subcategory2 is None:
+            raise ApiValueError('Either one of the sub/category V1 or V2 parameters '
+                                'must be specified')
+        if category:
+            data['category'] = category
+
+        if subcategory:
+            data['subcategory'] = subcategory
+
+        if subcategory2:
+            data['subcategory2'] = subcategory2
 
         if budget is None and duration is None:
             raise ApiValueError('Either one of the ``budget``or ``duration`` '
@@ -446,7 +444,7 @@ def post_job(self, buyer_team_reference, title, job_type, description,
 
     def update_job(self, job_id, buyer_team_reference, title, description,
                    visibility, category=None, subcategory=None, budget=None,
-                   duration=None, start_date=None, end_date=None, status=None):
+                   duration=None, start_date=None, status=None):
         """
         Update a job.
 
@@ -495,10 +493,6 @@ def update_job(self, job_id, buyer_team_reference, title, description,
                                    included the job will default to
                                    starting immediately.
 
-          :end_date:               (deprecated) This parameter remains
-                                   for compatibility reasons and
-                                   will be removed in future.
-
           :status:                 (required) The status of the job,
                                    e.g. 'filled'.
                                    Possible values are:

odesk/routers/offers.py

@@ -70,7 +70,7 @@ def send_client_offer(self, title, job_type, charge_rate,
                           contractor_org=None, context=None,
                           charge_upfront_percent=None, weekly_limit=None,
                           weekly_stipend=None, expires_on=None,
-                          close_on_accept=None):
+                          close_on_accept=None, related_jobcategory=None, milestone=None):
         """
         Send client offer to the freelancer.
 
@@ -102,18 +102,28 @@ def send_client_offer(self, title, job_type, charge_rate,
                                      Example: ``context[job_posting_ref] = {{ opening_id }} & context[job_application_ref] = {{ application_id }}``
                                      where ``job_posting_ref`` is a job key, for example ``~01c8e0xxxxxxxx05255``.
 
-          :charge_upfront_percent:   The percentage of the budget amount that the freelancer is paid on acceptance of the offer
+          :charge_upfront_percent:   (deprecated) This parameter remains for compatibility reasons and will be removed 
+                                     in next releases those come after February 6th 2015.
+                                     The percentage of the budget amount that the freelancer is paid on acceptance of the offer
                                      (for fixed price jobs only).
 
           :weekly_limit:             The maximum number of hours per week the freelancer can bill for.
 
           :weekly_stipend:           An additional payment to be issued to the freelancer each week.
 
-          :expires_on:               Time when the offer expires. This should be a UNIX UTC timestamp. For example: ``1400785324``.
+          :expires_on:               (deprecated) This parameter remains for compatibility reasons and will be removed
+                                     in next releases those come after February 6th 2015.
+                                     Time when the offer expires. This should be a UNIX UTC timestamp. For example: ``1400785324``.
 
           :close_on_accept:          If the value is ``1``, it automatically closes the related job post if this offer is accepted.
                                      The default value is ``1``. Valid values: ``0``, ``1``.
 
+          :related_jobcategory:      Related job category. For example: ``9``.
+
+          :milestones:               (required after February 6th 2015) Array of milestones for fixed-priced jobs in the following format: 
+                                     `milestones[0][$key]`, ..., `milestones[N][$key]`, where key is one of the following -
+                                     `milestone_description` (string), `deposit_amount` (float), `due_date` (string in format mm-dd-yyyy)
+
         """
         data = {}
 
@@ -155,6 +165,12 @@ def send_client_offer(self, title, job_type, charge_rate,
         if close_on_accept:
             data['close_on_accept'] = close_on_accept
 
+        if related_jobcategory:
+            data['related_jobcategory'] = related_jobcategory
+
+        if milestones:
+            data['milestones'] = milestones
+
         url = 'clients/offers'
         return self.post(url, data)
 

odesk/routers/provider.py

@@ -325,6 +325,15 @@ class Provider_V2(Namespace):
     api_url = 'profiles/'
     version = 2
 
+    def get_categories_metadata(self):
+        """
+        Returns list of all categories (v2) available for job/contractor profiles.
+
+        """
+        url = 'metadata/categories'
+        result = self.get(url)
+        return result.get('categories', result)
+
     def search_providers(self, data=None, page_offset=0, page_size=20):
         """Search providers.
 

odesk/routers/team.py

@@ -219,3 +219,36 @@ def get_snapshots(self, company_or_team_id, online=None, disabled=None):
             snapshots = [snapshots]
 
         return snapshots
+
+    def get_workdiaries_by_contract(self, contract_id, date, tz=None):
+        """
+        Retrieve workdiary snapshots by contract
+
+        *Parameters:*
+          :contract_id: The Contract ID.
+
+          :date:        The target date in `yyyymmdd` format.
+
+          :tz:          (optional) Time zone to use. Possible values:
+                          * 'mine' (default)
+                          * 'user'
+                          * 'gmt'
+
+        """
+        url = 'workdiarie/contracts/{0}/{1}'.format(contract_id, date)
+
+        data = {}
+
+        if tz:
+            assert_parameter('tz', tz, self.TZ_CHOICES)
+            data['tz'] = tz
+
+        result = self.get(url, data)
+        if 'error' in result:
+            return result
+
+        snapshots = result.get('snapshots', data).get('snapshot', [])
+        if not isinstance(snapshots, list):
+            snapshots = [snapshots]
+        
+        return result['snapshots']['user'], snapshots

odesk/tests.py

@@ -372,6 +372,10 @@ def test_team():
     eq_(te.get_workdiaries(1, 1, 1), (teamrooms_dict['snapshots']['user'],
         [teamrooms_dict['snapshots']['snapshot']]))
 
+    #test get_workdiaries_by_contract
+    eq_(te_v2.get_workdiaries_by_contract(1, 1), (teamrooms_dict['snapshots']['user'],
+        [teamrooms_dict['snapshots']['snapshot']]))
+
 
 teamrooms_dict_none = {'teamrooms': '',
                        'teamroom': '',
@@ -646,31 +650,16 @@ def patched_urlopen_hradjustment(*args, **kwargs):
 def test_hrv2_post_adjustment():
     hr = get_client().hr
 
-    # Using ``amount``
-    result = hr.post_team_adjustment(
-        1, 2, 'a test', amount=100, notes='test note')
-    assert result == adjustments[u'adjustment'], result
-
     # Using ``charge_amount``
     result = hr.post_team_adjustment(
         1, 2, 'a test', charge_amount=100, notes='test note')
     assert result == adjustments[u'adjustment'], result
 
     try:
-        # Using ``amount`` and ``charge_amount`` will raise error
-        hr.post_team_adjustment(
-            1, 2, 'a test', amount=100, charge_amount=110, notes='test note')
-        raise Exception('No error ApiValueError was raised when using'
-                        'both ``amount`` and ``charge_amount``')
-    except ApiValueError:
-        pass
-
-    try:
-        # If both ``amount`` and ``charge_amount`` are absent,
+        # If ``charge_amount`` is absent,
         # error should be raised
-        hr.post_team_adjustment(1, 2, 'a test', notes='test note')
-        raise Exception('No error ApiValueError was raised when both'
-                        'both ``amount`` and ``charge_amount`` are absent')
+        hr.post_team_adjustment(1, 2, 'a test', notes='test note', charge_amount=0)
+        raise Exception('No error ApiValueError was raised when ``charge_amount`` is absent')
     except ApiValueError:
         pass
 
@@ -717,11 +706,46 @@ def test_hr_restart_contract():
     'budget': 100,
     'duration': 10,
     'start_date': 'some start date',
-    'end_date': 'some end date',
     'skills': ['Python', 'JS']
 }
 
 
+job_data2 = {
+    'buyer_team_reference': 111,
+    'title': 'Test job from API',
+    'job_type': 'hourly',
+    'description': 'this is test job, please do not apply to it',
+    'visibility': 'odesk',
+    'subcategory2': 'Web & Mobile Development',
+    'budget': 100,
+    'duration': 10,
+    'start_date': 'some start date',
+    'skills': ['Python', 'JS']
+}
+
+
+def patched_urlopen_job_data_parameters2(self, method, url, **kwargs):
+    post_dict = urlparse.parse_qs(kwargs.get('body'))
+    post_dict.pop('oauth_timestamp')
+    post_dict.pop('oauth_signature')
+    post_dict.pop('oauth_nonce')
+    eq_(
+        dict(post_dict.items()),
+        {'buyer_team__reference': ['111'],
+         'subcategory2': ['Web & Mobile Development'],
+         'title': ['Test job from API'],
+         'skills': ['Python;JS'], 'job_type': ['hourly'],
+         'oauth_consumer_key': ['public'],
+         'oauth_signature_method': ['HMAC-SHA1'], 'budget': ['100'],
+         'visibility': ['odesk'],
+         'oauth_version': ['1.0'], 'oauth_token': ['some token'],
+         'oauth_body_hash': ['2jmj7l5rSw0yVb/vlWAYkK/YBwk='],
+         'duration': ['10'],
+         'start_date': ['some start date'],
+         'description': ['this is test job, please do not apply to it']})
+    return MicroMock(data='{"some":"data"}', status=200)
+
+
 def patched_urlopen_job_data_parameters(self, method, url, **kwargs):
     post_dict = urlparse.parse_qs(kwargs.get('body'))
     post_dict.pop('oauth_timestamp')
@@ -731,7 +755,7 @@ def patched_urlopen_job_data_parameters(self, method, url, **kwargs):
         dict(post_dict.items()),
         {'category': ['Web Development'], 'buyer_team__reference': ['111'],
          'subcategory': ['Other - Web Development'],
-         'end_date': ['some end date'], 'title': ['Test job from API'],
+         'title': ['Test job from API'],
          'skills': ['Python;JS'], 'job_type': ['hourly'],
          'oauth_consumer_key': ['public'],
          'oauth_signature_method': ['HMAC-SHA1'], 'budget': ['100'],
@@ -750,6 +774,22 @@ def test_job_data_parameters():
     hr.post_job(**job_data)
 
 
+@patch('urllib3.PoolManager.urlopen', patched_urlopen_job_data_parameters2)
+def test_job_data_parameters_subcategory2():
+    hr = get_client().hr
+    hr.post_job(**job_data2)
+
+
+@patch('urllib3.PoolManager.urlopen', patched_urlopen_job_data_parameters)
+def test_job_data_no_category():
+    hr = get_client().hr
+
+    try:
+        hr.post_job('111', 'test', 'hourly', 'descr', 'odesk')
+        raise Exception('Request should raise ApiValueError exception.')
+    except ApiValueError:
+        pass
+
 provider_dict = {'profile':
                  {u'response_time': u'31.0000000000000000',
                   u'dev_agency_ref': u'',