hh-stats 1.4.0

Utility for a collection of a vacancies stats from hh.ru service

Features

• vacancies loading from:

  • hh.ru service API;

  • JSON files;

• collection of vacancies key skills;

• collection for every vacancy key skill:

  • request frequency;

  • median salary:

    • minimal;

    • maximal;

• vacancies search options:

  • area list (allowed values (in JSON format): https://api.hh.ru/areas);

  • specialization list (allowed values (in JSON format): https://api.hh.ru/specializations);

  • additional search query (it supports a query language: https://hh.ru/article/1175);

  • search fields for the search query (allowed values: name, description);

  • search vacancies only with a salary;

  • begin of the time period for an analysis (in the ISO 8601 or the human-readable format; see below for details);

  • end of the time period for an analysis (in the ISO 8601 or the human-readable format; see below for details);

  • time increment for an iteration over the time period (in the human-readable format; see below for details);

• automatic conversion of a salary currency;

• automatic separation of unseparated skills;

• support of skills aliases (see below for details);

• output of a collected stats:

  • in a format:

    • raw (a vacancy list in a JSON format; see below for details);

    • CSV;

    • SVG;

  • to:

    • specified file;

    • stdout (only for raw and CSV formats);

    • window via Matplotlib library (only for SVG format);

• support of a specification of a minimal output value of skills requests frequencies;

• automatic adding of an output file extension, depending on a specified format.

Installation

$ pip install hh-stats

Usage

$ hh-stats -v | --version
$ hh-stats -h | --help
$ hh-stats [options]

Options:

• -v, --version — show the version message and exit;

• -h, --help — show this help message and exit;

• -a AREA [AREA...], --areas AREA [AREA...] — vacancies areas (allowed values (in JSON format): https://api.hh.ru/areas; default: ['1']);

• -s SPECIALIZATION [SPECIALIZATION...], --specializations SPECIALIZATION [SPECIALIZATION...] — vacancies specializations (allowed values (in JSON format): https://api.hh.ru/specializations; default: ['1.221']);

• -q QUERY, --query QUERY — the additional search query (it supports a query language: https://hh.ru/article/1175);

• -p {name,description} [{name,description}...], --query-properties {name,description} [{name,description}...] — search fields for the search query (allowed values: name, description; default: ['name', 'description']);

• -r, --salary-required — search vacancies only with a salary;

• -b ANALYSIS_BEGIN, --analysis-begin ANALYSIS_BEGIN — a begin of the analysis time period in the ISO 8601 or the human-readable format (default: 1 month ago);

• -e ANALYSIS_END, --analysis-end ANALYSIS_END — an end of the analysis time period in the ISO 8601 or the human-readable format (default: now);

• -I ANALYSIS_INCREMENT, --analysis-increment ANALYSIS_INCREMENT — the analysis time increment in the human-readable format (see below for details);

• -F REQUEST_FREQUENCY, --request-frequency REQUEST_FREQUENCY — the maximal request frequency (default: 30);

• -S PAGE_SIZE, --page-size PAGE_SIZE — the maximal page size (default: 500);

• -V VALUE_OF_INTEREST, --value-of-interest VALUE_OF_INTEREST — the minimal value of an interest (default: 5);

• -E, --error-on-limit — throw an error on an exceeding of the search limit (2000 vacancies);

• -D [SKILLS_DELIMITER...], --skills-delimiters [SKILLS_DELIMITER...] — delimiters for unseparated skills (default: [',', ';']);

• -A SKILLS_ALIASES, --skills-aliases SKILLS_ALIASES — the path to a file with skills aliases in a JSON format (see below for details);

• -O {num,min,max}, --order {num,min,max} — the order of stats items (default: num);

• -f {raw,csv,svg} [{raw,csv,svg}...], --format {raw,csv,svg} [{raw,csv,svg}...] — the output format (default: ['svg']);

• -i INPUT [INPUT...], --inputs INPUT [INPUT...] — input paths;

• -o OUTPUT, --output OUTPUT — the output path.

Timestamp format

ISO 8601 format

YYYY-MM-DDTHH:MM:SS±HHMM

Human-readable format

± <quantity> <unit> <modifier> <reference point>

Units: year, month, week, day, hour, minute, second.

Modifiers: from, before, after, ago, prior, prev, last, next, previous, end of, this, eod, eom, eoy.

Reference points: months, weekdays, yesterday, today, now, tomorrow, noon, afternoon, lunch, morning, breakfast, dinner, evening, midnight, night, tonight.

E.g.:

5 minutes from now
5 minutes ago
1 hour from noon
last week
2 weeks from tomorrow
3 hours from next monday

See for details: https://github.com/bear/parsedatetime.

Human-readable time delta format

E.g. 5 d 12 h 23 m 42 s.

See for details: https://github.com/wroberts/pytimeparse.

Skills aliases format

Skills aliases format in the JSON Schema format:

{
  "type": "object",
  "patternProperties": {
    "^.+$": {
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1
      },
      "uniqueItems": true,
      "minItems": 1
    }
  },
  "additionalProperties": false,
  "minProperties": 1
}

E.g.:

{
  "HTML": ["HTML5"],
  "CSS": ["CSS3"],
  "JavaScript": ["ES5", "ES6", "ES7", "ES2015", "ES2016", "ES2017"],
  "PHP": ["PHP5", "PHP7"],
  "Python": ["Python2", "Python3"],
  "Go": ["Golang"],
  "C++": ["C/C++", "C++11", "C++14", "C++17"],
  "bash": ["shell"]
}

Vacancy list format

Vacancy list format in the JSON Schema format:

{
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "id": {
        "type": "string",
        "pattern": "^\\d+$"
      },
      "skills": {
        "type": "array",
        "items": {
          "type": "string",
          "minLength": 1
        },
        "minItems": 1
      },
      "salary": {
        "type": "object",
        "properties": {
          "minimal": {
            "$ref": "#/definitions/amount"
          },
          "maximal": {
            "$ref": "#/definitions/amount"
          }
        },
        "required": [
          "minimal",
          "maximal"
        ],
        "additionalProperties": false
      }
    },
    "required": [
      "id",
      "skills",
      "salary"
    ],
    "additionalProperties": false
  },
  "minItems": 1,
  "definitions": {
    "amount": {
      "oneOf": [
        {
          "type": "null"
        },
        {
          "type": "number",
          "minimum": 0
        }
      ]
    }
  }
}